The Arsenal Files 6/The Arsenal Files 6 (Arsenal Computer).ISO/os2/pmsx211b.zip/PMSNDX.HLP

OS/2 Help File | 1996-01-07 | 437KB | 4,082 lines

ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ

                                   PMsndX 2.11
                                       by
                                William S. Hiles
                             copyright WiSHware Inc.

Please see Known Problems with this release for important information before
using this version of PMsndX.

Firstly, thank you for using the new 2.XX version of PMsndX. If you are a user
of the 1.XX program called PMsndX, you have probably been surprised that you
have not found the program called PMsndX.EXE any longer.  There is a good
reason for that.  PMsndX has been broken into more than one program.

For clarity, the term EdSndX is the name of the sound editor, the term PlSndX
is the name of the sound player, and the term PMsndX is the term used to
describe a feature that is common to both EdSndX and PlSndX.

This is the second generation of PMsndX.  In versions prior to 2.0, PMsndX was
comprised of a single program which performed the same functions of both EdSndX
and PlSndX but operated on a single sample at a time.  With the introduction of
version 2.0, PMsndX has been divided into a family of programs which are more
specialized and intended to meet the needs of a broader audience.

The general idea of the new organization is to provide a more focused goal for
the individual programs along the same theme.  The general purpose of this
family of programs is to perform various functions for virtually any sound
format. In version 1.xx, the program started out to simply convert formats,
then grew into an editor, then a playback tool, and so forth.  The result was a
program that was somewhat unfocused and did not provide a consolidated user
interface. Version 2.0 is a complete rewrite of the previous user interface
which takes advantage of lessons learned during the development of 1.xx.

All of the PMsndX family of software utilize common resources such as the
initialization file and registration information.  The Properties boxes for all
of the programs are consistent and will affect one another except where noted
as a specific feature of one program.  As a result, the Properties box may
contain items that are not necessarily related to the particular program being
used but can be changed from any program in the family. This approach provides
a common and consistent approach to controlling the options for the programs.

The programs in the PMsndX family also were written specifically for OS/2 and
you will not find another program with the same look and feel under any other
operating system.  The user interface was designed from scratch under OS/2 and
is not a port from any other system.  As a result, it takes full advantage of
the capabilities of OS/2 and has been written to conform to IBM's goals with
the Common User Access specifications.

EdSndX: provides most of the functionality that was in PMsndX prior to 2.0.
Notably missing from EdSndX is the ability to play from the command line.  This
rewrite took about 6 months to complete and provides a complete Multiple
Document Interface (MDI) capability.  Hence, the name change as a result of the
change from a do-all program to a more capable sound editor.

PlSndX: provides the ability to play any of the sound samples which can be
loaded by EdSndX from the command line or through Drag/Drop.  PlSndX does not
provide any editing features but does provide the capability to save a sample
in any of the supported formats.  Further, it has some enhancements to reduce
the memory requirements of the program during playback.


ΓòÉΓòÉΓòÉ 2. EdSndX ΓòÉΓòÉΓòÉ

                                   PMsndX 2.11
                                       by
                                William S. Hiles
                             copyright WiSHware Inc.

EdSndX is one part of the family of programs grouped under the name PMsndX.
EdSndX goes beyond just a cut and paste tool for sound by providing a rich set
of tools for manipulating samples in memory. EdSndX utilizes multiple threads,
the clipboard, Drag/Drop, and the MMPM/2 services present in the Workplace
Shell to provide a robust editor for everyone from the beginner to the more
advanced users.  Like all of the tools in the PMsndX family, EdSndX can be run
on any system irregardless of whether MMPM/2 is installed because all of the
routines were written from hand including the animated buttons and routines for
reading and writing the various sound formats.  Additional advantages to this
approach include a greater degree of control and some customized features like
the volume control that you will not find anywhere else.  The obvious
disadvantage is that the routines that IBM provides in the MMPM/2 DLLs have
been thoroughly tested and may be more robust that the ones that I have
provided.


ΓòÉΓòÉΓòÉ 2.1. Control Panel ΓòÉΓòÉΓòÉ

The control panel is the central point of control for EdSndX.  From the control
panel, the EDITOR, PROPERTIES, TOOLS, and HELP can be launched.  The control
panel has a system menu which provides access to the standard OS/2 menu
controls.  Additionally, the system menu for the control panel provides access
to the ABOUT, WELCOME, HELP, RESET SIZE, PROPERTIES, and FILE LIST.

The control panel is a window under the OS/2 Workplace Shell and as such can be
resized using the border of the window. See reset size for instructions on
restoring the default size.

The control panel is also the place to receive drag/drop operations.  Such
operations are accomplished by dragging a sound file to the control panel and
dropping it anywhere within the border of the panel and below the titlebar.
EdSndX will automatically open an editor for the sample. See drag/drop for more
information on  performing drag/drop operations.


ΓòÉΓòÉΓòÉ 2.1.1. System Menu ΓòÉΓòÉΓòÉ

As with any OS/2 program written for the Presentation Manager, EdSndX has an
icon in the top left corner of the control panel for accessing a system menu.

The menu items provided in the system menu are:

 Restore        Restore the windows after being minimized
 Move           Move the control window
 Size           Resize the main control panel
 Minimize       Minimize all of the windows of EdSndX to an icon
 Close          Close the all windows and exit
 About          Display information about the author and version and
                registration
 Welcome        Display information about what is new to this version
 Help           Bring up the help system
 Reset Size     Reset the size of the main control panel to the default
 Properties     Change program operational parameters
 File List      List open files and switch focus


ΓòÉΓòÉΓòÉ 2.1.1.1. Restore ΓòÉΓòÉΓòÉ

During the use of EdSndX, the user may select to Minimize the windows to an
icon on the desktop.  To restore the window from the icon the user may either
double click on the icon or may press a mouse button while the pointer is over
the icon to bring up the system menu and select the restore item.


ΓòÉΓòÉΓòÉ 2.1.1.2. Move ΓòÉΓòÉΓòÉ

EdSndX provides the standard controls for moving the windows around on the
desktop.  It is generally easiest to use the mouse to select the titlebar of
the window and drag the window to the new location.  If the user uses the
system menu to move the window, the mouse will be centered in the control
window and any movement of the mouse will move the window until a mouse button
is pressed.


ΓòÉΓòÉΓòÉ 2.1.1.3. Size ΓòÉΓòÉΓòÉ

EdSndX provides the standard control for resizing the main control panel.  When
resizing, the main control panel will automatically adjust the vertical size of
the window to maintain the aspect of the buttons.


ΓòÉΓòÉΓòÉ 2.1.1.4. Minimize ΓòÉΓòÉΓòÉ

All of the windows of EdSndX can be minimized quickly by either selecting the
minimize button on the upper right corner of the control panel or by using the
Minimize menu item of the system menu.  Either action performs the same
function.


ΓòÉΓòÉΓòÉ 2.1.1.5. Close ΓòÉΓòÉΓòÉ

To exit EdSndX the user can select the Close menu item from the system menu.
This is the default selection of the menu which enables the user to double
click on the EdSndX icon in the top left corner of the control panel to exit
the program.

When the any of the PMsndX programs are terminated, if changes have been made
to the Properties box, the data will be saved to the initialization file before
the program exits.  Before exiting, EdSndX requests verification that the user
wants to exit to prevent accidentally exiting. All windows of EdSndX, including
any dialog boxes, are removed from the screen when the program terminates.

If the data in the memory buffers has been modified, EdSndX will warn the user
that there are modified buffers and ask for verification that the user really
wants to exit.


ΓòÉΓòÉΓòÉ 2.1.1.6. About ΓòÉΓòÉΓòÉ

To find the version and other information about EdSndX the About menu item can
be selected from the system menu. The registration can be updated by pressing
the REGISTER button.

PMsndX is just one of the programs written by the Author for Intel based
machines.  All programs developed under the WiSHware Inc. name have been
developed solely by the author (duhh, the Author is the sole member of the
company) and are copyrighted by US Copyright laws.


ΓòÉΓòÉΓòÉ 2.1.1.7. Welcome ΓòÉΓòÉΓòÉ

The HISTORY.TXT file contains a very complete list of all the changes between
each of the versions.  When viewed as a whole, it also summarizes the total
functionality of PMsndX.  Each version has specific changes which are
highlighted in the Welcome display. This display also shows the current
registration status of the program and the registration can be updated by
pressing the REGISTER button.


ΓòÉΓòÉΓòÉ 2.1.1.8. Help ΓòÉΓòÉΓòÉ

PMsndX is equipped with extensive on line help that can be accessed by
selecting HELP from the system menu or from the main control panel.  When this
item is selected a window will appear which will display the start of the help
information. Help can also be accessed by pressing Alt-H or the F1 key.

Links to other text is displayed in a blue-green color and can be selected to
jump to that description in the text. When the control panel buttons appear in
a tabular form, the buttons are active links in the help like the blue-green
colored text.  Pressing these buttons will jump to the respective text.


ΓòÉΓòÉΓòÉ 2.1.1.9. Reset Size ΓòÉΓòÉΓòÉ

The default button size for the display is 64x64. At any time, the user may
select to reset the size of the main control panel so that it returns to the
defaults.  The main control panel may be resized, using the border of the
window.


ΓòÉΓòÉΓòÉ 2.1.1.10. Program Properties ΓòÉΓòÉΓòÉ

The Properties menu item will bring up the same dialog that is accessed from
the PROPS button on the control panel.


ΓòÉΓòÉΓòÉ 2.1.1.11. File List ΓòÉΓòÉΓòÉ

Each window of the editor is part of the same thread as the control panel.
Although these are part of the same thread, they have been set up to also
appear in the task list. This has the advantage that each edit window can be
brought to the focus simply by bringing up the task list.  But, this has some
disadvantages too.  Firstly, EdSndX allows the operator to open more than one
copy of the same file at a time and multiple new files are simply named
Untitled. As a result, it is difficult to tell which file is which in the task
list.  Secondly, the task list provides the ability to close a particular
window by killing its thread.  Since all edit windows are a member of the same
common thread, killing any one of them kills the thread and all windows
associated with it.  By creating a File List, unique numbers are assigned to
each file that allow the operator to identify the file that is being used.
These numbers are also by the REXX processor as handles to identify the
samples.

To give a particular window a focus select the name of the file to receive the
focus and either select the APPLY button or double click on the entry. If the
selected window has been minimized, it will be restored upon receiving the
focus.


ΓòÉΓòÉΓòÉ 2.1.2. Resizing the main panel ΓòÉΓòÉΓòÉ

In accordance with the recommended Common User Access (CUA) guidelines, the
main control panel may be resized using the border of the window.  The
horizontal and vertical proportions of the buttons are always fixed such that
the overall window proportions will display the buttons properly. When the
width of the main panel is changed, the height is automatically adjusted to
maintain the proper shape of the buttons.

Note:  Note.  To resize the window, either the corners or the vertical sides of
       the window must be used.  The horizontal sides of the window have no
       effect when used alone.


ΓòÉΓòÉΓòÉ 2.1.3. Buttons ΓòÉΓòÉΓòÉ

The main control panel provides the user with access to all tools and functions
through a set of buttons.  Each button contains an icon and a single word which
describes the function of the button. The buttons have been designed as toggle
type push buttons.  To select a particular button, click over the desired area
with the first mouse button.  This will depress the button and activate a
dialog for the desired function.  The dialogs present information to the user
about the desired operation and request input from the user to complete the
operation.  The exception to this operation is the Help, and New buttons
because they can be used even when an instance of their respective function has
been created.

The control panel is the main point of control for both activating and
deactivating a particular function.  The dialog boxes can be removed from the
screen by positioning the mouse over a depressed button and pressing the first
mouse button.  The dialog box will be removed and the button will return to the
non-depressed position. It is important to note that when a dialog box is
removed through this means, any information in the dialog is ignored and the
function is canceled.  For each dialog box, the user must enter all of the
information required and then select the appropriate action on the push buttons
at the bottom of the dialog box.

Now for the buttons.  There are five buttons on the main control panel.  These
are listed below with a brief explanation of their function.

                Opens and reads a new sample file
                Opens an empty window for editing
                Opens up properties display
                Opens the toolbox for performing DSP operations
                Starts the help window


ΓòÉΓòÉΓòÉ 2.1.3.1. Open ΓòÉΓòÉΓòÉ

The dialog box for opening a file and reading the sample into memory is
accessed from the OPEN button on the main control panel.  When reading in a
file, PMsndX will attempt to open the file as the type indicated by the
extension on the filename.  However, in the event that the file cannot be
loaded by the extension, PMsndX will automatically try to determine the type of
the file as it reads it based on any header that may be present.  If the sample
header does not match any of the known header types, PMsndX will refuse to load
the file unless the format of the file is specified in the OPEN dialog box.

Note:  The formats that are supported by the family of PMsndX programs are
       listed in the OPEN dialog box.  If PMsndX has not been registered, only
       the WAV and AU formats will be available.

 The file box allows for multiple selections by using either the CTRL or SHIFT
 keys in combination with the mouse pointer.  When multiple selections are
 used, the Full Filename field is updated with the last item selected or
 deselected.  When the LOAD button is pressed, the selections are all fully
 qualified and each file starts loading sequentially as if they had been
 entered on the commandline.

 When loading a file, the user may select to force PMsndX to load a file in a
 specific format.  This is required to load headerless formats (i.e. the
 formats marked as RAW).  To override the file format, select one of the
 formats in the Format pulldown list.

 Note:  If a Format override is specified, the file must still match the given
        format if it contains a header.  EdSndX will automatically recognize
        the header format and load it using the correct format.

 The default filename to open is the last file that was successfully opened.
 The name of the file to be opened may be selected in a number of ways.  The
 filename may be entered in the Full Filename entry field.  The name may be
 fully qualified with a drive and directory, or may be any valid filename.  The
 name will be resolved when passed to the OS/2 IO procedures.  The filename may
 also be selected by chosing the drive, directory, and name using the
 corresponding list boxes.  The files to be displayed in the File display are
 controlled by the File Mask selected. Finally, whenever a file is successfully
 loaded, it is added to the Full Filename list box.  The previously loaded file
 names can be displayed by pulling down the list box.

 Note:  The cache of successfully opened files can be saved between sessions by
        selecting Save file Open paths in the Properties box.

 Once a file has been selected, either double click on the file name or press
 the Load button.  During the time that the file is being loaded, the user may
 press the Abort button to stop the loading process. The process for opening a
 file initiates a new thread for each file name loaded.  As a result, if more
 than one is being loaded, there is no way to abort the loading of a file once
 the next file has started loading. Additionally, if the OPEN dialog is
 dismissed while the loading thread has started, there is no way to abort the
 load.

 The File Mask list box contains the common filters for extensions that PMsndX
 recognizes.  This list box can be edited for any mask that the user needs.

 The Format list box contains the common file FORMATS that PMsndX recognizes.
 Each format identifies the type as well as the extension that PMsndX
 recognizes.  This list is not editable and is loaded with only those formats
 that are currently supported.  If PMsndX has not been registered, the listed
 formats may be considerably less than the total of fully supported formats.

 By default, the OPEN dialog box is automatically dismissed when the file has
 been loaded.  When multiple files are selected to be loaded, the dialog is
 dismissed if any one of the selected files is successfully loaded.  If an
 error occurs during the loading process, the dialog will not automatically
 dismiss itself.  To disable this feature (i.e. force the dialog box to remain
 visible even after a file has been loaded) deselect the AUTO Dismiss checkbox
 in the upper right corner of the window.


ΓòÉΓòÉΓòÉ 2.1.3.2. New ΓòÉΓòÉΓòÉ

To facilitate creating new sound files (through any input means such as the
microphone, line input, or the clipboard), an empty edit window can be opened
by selecting NEW from the control panel.  The initial file name will be
undefined and the SAVE AS dialog box will automatically be required to save the
file with a user defined file name.

See Record setup for instructions on recording a sample.


ΓòÉΓòÉΓòÉ 2.1.3.3. Properties ΓòÉΓòÉΓòÉ

 The properties button on the control panel provides access to the settings for
options that are stored in the initialization file between sessions.  The
properties dialog can be accessed from this button or through the system menu.


ΓòÉΓòÉΓòÉ 2.1.3.4. Tools ΓòÉΓòÉΓòÉ

The toolbox is a means to access special digital processing routines.  The
toolbox is displayed as a notebook in which each page represents a different
tool with specific settings that are related to that tool. See Tools for a full
description of the toolbox and its controls.

The toolbox represents a common resource for any edit window that is open.  As
such, the toolbox must be associated with a particular edit window before it
can be used.  When the toolbox is associated with a window, it will display the
name of the file for the association in the titlebar. See Editor Switch to for
associating the toolbox with a particular edit window.


ΓòÉΓòÉΓòÉ 2.1.3.5. Help ΓòÉΓòÉΓòÉ

To start the help viewer for EdSndX, the HELP button may be pressed.
Additionally, the help may be accessed through the system menu help item.
Further, help may be accessed from any window by pressing the F1 key.


ΓòÉΓòÉΓòÉ 2.1.3.6. Footnote ΓòÉΓòÉΓòÉ

The main control panel may optionally display a footnote which provides a short
description of the current item under the mouse pointer.  This footnote display
can be turned on or off through the properties dialog box.  Note that when the
footnote display is turned on or off, the change does not take effect till the
next time in which EdSndX is executed.


ΓòÉΓòÉΓòÉ 2.2. Editor ΓòÉΓòÉΓòÉ

The editor is the main point of control for manipulating samples in memory.
Whenever a sample is loaded into memory, it is displayed in an edit window.
There can be multiple samples open simultaneously and each has an associated
window.  Additionally, when a new sample is to be created, an edit window is
opened for the creation of the data.

The following figure shows all of the fields of an edit window for a sample
containing two channels.


ΓòÉΓòÉΓòÉ 2.2.1. Resizing the editor ΓòÉΓòÉΓòÉ

EdSndX has the ability to store the size of the edit window between sessions.
This feature can be disabled through the properties dialog by checking the Save
Window positions checkbox.  If this box is cleared, the editor will not save
its size and will automatically open with a default window size that is
reasonably sized to display all information.

When resizing the editor, all of the windows of the editor automatically resize
too.  It is possible to size the editor such that the text of some windows will
not be adequately sized to hold all information.


ΓòÉΓòÉΓòÉ 2.2.2. Mouse Buttons ΓòÉΓòÉΓòÉ

IBM has not defined the usage of the mouse buttons in the CUA guidelines.
EdSndX uses the mouse for selection of fields within the graphical displays and
for pulling up menus for special operations within the control windows.

Button 1 (Left Mouse Button) is used to edit data in control windows or popup
menus in the graphical windows by clicking the mouse twice (double clicking).

Button 2 (Right mouse Button) is used to access popup menus for a control
window or the graphical windows by a single click of the mouse.

Each of the graphical displays provides popup menus which allow the operator to
select marker positions within the window.  These same markers can be set
through the menu bar. The control windows also provide special popup menus for
setting their values and are identical to those found in the menu bar.


ΓòÉΓòÉΓòÉ 2.2.3. Titlebar ΓòÉΓòÉΓòÉ

The titlebar of the edit window displays the file name of the current sample
for the window.  This is the same name that appears in the File list on the
main control panel.  If a file has no filename, the titlebar shows (not named).
Since multiple copies of the same file can be opened simultaneously, each file
is displayed with a unique number in all references to the file names.  This
additional information can be used by the operator to determine which edit
window is associated with the name in the file list.


ΓòÉΓòÉΓòÉ 2.2.4. Regions ΓòÉΓòÉΓòÉ

The editor is divided into regions which display information about a particular
sample.  These regions are menu, info*, full graph, display position, channel
data, controls, and audio. Each region serves a common function for the editing
of data as explained below.

Note:  * The info region is optional and may be removed or added using the
       Display Info.

 menu              Select options and perform operations using the pulldown
                   menu
 info*             Display and change information in the header of a sample
 full graph        Displays the first channel of a sample and provides visual
                   clues for the selected range within the sample
 display position  Indicates the viewable regions of the sample and scrolls
                   within the full graph
 channel data      Displays one or all channels of a sample
 controls          Provides display controls and feedback on operations
 audio             Provides access to MMPM/2 if present


ΓòÉΓòÉΓòÉ 2.2.4.1. Menu ΓòÉΓòÉΓòÉ

The menu bar is used to access all of the features of the editor. See Menu Bar
for a complete description of the menu structure.


ΓòÉΓòÉΓòÉ 2.2.4.2. Info ΓòÉΓòÉΓòÉ

The information display of the editor is optional.  The menu item Display Info
can be used to change the status of the display of the information area.

The information display contains all of the data needed to save a file in any
format.  The information region does more than simply display the header
information for a sample.  It also allows the operator to edit the various
attributes about a sample.  Many sample formats can save the data in a number
of different styles but some are limited in their representation.  Changes made
to the information area may be overridden when a sample is saved to ensure that
the sample conforms to the particular sample format. The data displayed in the
editor information region is identical to that of the toolbox Info page with
the exception that the toolbox information display does not allow the operator
to edit the information.

The following information is displayed in this region:

 Format            the machine or operating system that the particular format
                   is native to
 Type              the format specification for a file
 Style             the data style of each samplesample
 Size              the size of each sample
 Channels          the number of channels contained in the file
 Rate              the sampling rate used to record and play the samples
 Samples           the number of samples in the file
 Order             the ordering of the bytes within each sample
 Comment           the comment associated with the samples


ΓòÉΓòÉΓòÉ 2.2.4.2.1. Format ΓòÉΓòÉΓòÉ

For every operating system, the manufacturer seems to choose to create a new
audio format which is native to the hardware of the machine.  As a side note,
PMsndX was created because there are so many sample formats in use that there
was a need to convert samples from one format to another so that they could be
shared between machines.

The pulldown list for the Format of a file allows the operator to select a
particular format and automatically change the other fields in the information
display to reflect any requirements of the selected format.  This is an
important feature because some sample formats do not support all styles and
sizes of data.  As an example, if a sample is currently a sun .AU format, when
it is changed to a OS/2 .WAV file, the style will automatically change to
Signed. This is because the .WAV format does not support u-law styles.  Also,
the Sun .AU format is a big-endian format whereas the .WAV format is a
little-endian format.

The selections in this list are identical to the selections provided by the
Format toolbox page.  See FORMATS for a description of the formats supported by
the PMsndX programs.  The significant difference in this field is that it does
not automatically change the extension of the file to be saved.

The format RAW is a special format which is a file containing raw data without
a header.  Since a RAW file does not contain the necessary information to load
it, PMsndX will request that the user provide the necessary information to
identify the file including the style, size, and order of the samples.
Additionally, the number of channels may be required for a file.  When the RAW
format is used, the Type information field will indicate the actual RAW type.


ΓòÉΓòÉΓòÉ 2.2.4.2.2. Type ΓòÉΓòÉΓòÉ

Every machine and operating system type listed in the Format list box
correspond to a defined standard format.  Every standard format defines the
style, size, and order of the data that can be stored in the file.  Some
formats support multiple styles and sizes and some even support different
orders.  Changes to this field are automatically reflected in the filename by
changing the extension of the file to that of the selected type.

The type of file is identified by both a standard name and a file type.  The
standard name is used to indicate some document or name that a manufacturer has
chosen for the format.  The file type is listed in parenthesis and identifies
the extension that the file is normally saved with.  When a file is saved, the
file extension is used to determine the way that the file is saved or loaded
unless an override is used in the file dialog box.  This field indicates the
anticipated data format for each of the file types supported by PMsndX.

The selections in this list are identical to the selections provided by the
Format toolbox page.  See FORMATS for a description of the formats supported by
the PMsndX programs.


ΓòÉΓòÉΓòÉ 2.2.4.2.3. Style ΓòÉΓòÉΓòÉ

The style of a sample indicates the interpretation of the bits in the file
which is stored on disk.  PMsndX programs support three basic styles including
Signed, Unsigned, and U-Law

Signed data indicates that the sequence of bits for each sample contains a bit
in the highest position to indicate that the sample is either positive or
negative.  As an example, for an eight bit sample format which is signed (in
which the bits are numbered from left to right from 7 to 0) the bit numbered 7
is reserved to indicate the sign.  All data is converted to signed data when it
is stored in memory.

Unsigned data indicates that there is no sign bit in the data.  Consequently,
the data may only take on positive values.  PMsndX automatically converts all
unsigned data to signed data as it stores it in memory.

U-Law data indiates that 16 bits of data has been compressed into 8 bits of
storage space when saved to disk.  This format uses a compression technique
which is lossy because it does not store the exact samples and the sample
cannot be exactly recreated from the file once it has been saved. U-Law is one
of the most popular formats on the internet because the storage space is small
and the loss in quality is tolerable to the human ear.  U-Law capitolizes on
the fact that the human ear cannot distinguish frequencies outside of a
particular range and also cannot easily distinguish between very similar
frequencies.

Not all sample formats support all styles.  If a sound format is selected which
does not support a particular style, EdSndX will automatically use the correct
style required by that format.  To determine if a format supports a particular
style, change the style first, and then select the particular format.  If the
format does not support the selected style, the style field will change to the
supported style.

When a RAW format is loaded into memory, the operator inadvertantly specifies
the style of the data when the format is specified.  For example, RAW (.sb)
indicates signed data from the first letter in the extension.


ΓòÉΓòÉΓòÉ 2.2.4.2.4. Size ΓòÉΓòÉΓòÉ

All data is represented by a series of bits.  A bit is the smallest piece of
information that the computer can manipulate.  16 bit samples are called WORDS
and 8 bit samples are called BYTES. The groupings of bits indicate the quality
of the sample that is stored in memory or in a file.  A larger number of bits
represents higher quality sound; however, a larger number of bits represents
more storage space too. PMsndX can deal with samples which are stored in any
size of up to 16 bits.

The size of a sample is an important factor when playing audio.  Some sound
adapters do not support 16 bit samples and cannot play such samples.  PMsndX
can still play these samples in the lower quality 8 bit sample format.  This
feature can be defeated using the Play 16 bits on 8 bit audio property.

Some sizes are not supported by all formats and in some cases, the style of the
data is dependent on the size.  As an example, .WAV files which are 16 bits
must be signed whereas 8 bit samples must be stored as unsigned.  The .hcm
format only supports 8 bit data.  PMsndX considers the size of a sample to be
the most imporant factor when converting data between formats in order to
maintain the same quality of data once saved to disk.  However, if a format
does not support 16 bit data, PMsndX will automatically change the size to 8
bits when it saves the file or when the format is changed.

When a RAW format is loaded into memory, the operator inadvertently specifies
the size of the data by the format selected.  As an example, RAW (.sb)
indicates that the format is 8 bits because the second letter is b for byte.


ΓòÉΓòÉΓòÉ 2.2.4.2.5. Channels ΓòÉΓòÉΓòÉ

Many audio formats support more than one channel.  The channels in a sample
affect the memory requirements of the sample and the display of the data.  For
this reason, changing the number of channels requires that the data for the
file be manipulated.  To change the number of channels for a sample, use the
Avg or Dupe tools.

When a RAW format is loaded into memory, the operator will be required to
specify the number of channels of the data because RAW formats do not contain
headers to allow PMsndX to determine the number of channels in the file.
Additionally, when a raw format is loaded, it is assumed that the channels are
interleaved in the sample.  There are formats which do not interleave the
channels and these cannot be loaded without headers.


ΓòÉΓòÉΓòÉ 2.2.4.2.6. Rate ΓòÉΓòÉΓòÉ

The rate field indicates that rate in samples per second that a sample was
recorded and stored.  The rate determines how quickly the samples are playbed
back also.  When the rate of playback is changed, the number of samples stored
in memory changes and so this field is not editable through the information
display.  See Rate or Speed for tools to change the rate of a sample.

When a RAW format is loaded into memory, the operator will be required to
specify the rate of the data that is stored in the file.  This is because there
is no header in the file to indicate the rate of the data.


ΓòÉΓòÉΓòÉ 2.2.4.2.7. Samples ΓòÉΓòÉΓòÉ

The number of samples in the file is indicated by both the total number of
samples and the samples per channel.  When a file is made of a single channel,
both numbers will be identical.  The length of the file determines the memory
requirements of the sample.  The length is affected by almost all operations in
the toolbox.


ΓòÉΓòÉΓòÉ 2.2.4.2.8. Order ΓòÉΓòÉΓòÉ

Every machine conforms to either BIT ENDIAN or LITTLE ENDIAN.  The order of the
bits in the sample are important because they determine the sequence of the
bits in the bytes.  Intel based machines are LITTLE ENDIAN because they reverse
the order of bytes that make up a sample.  Motorola based processors use BIG
ENDIAN. The tradeoffs for using BIG and LITTLE endian are minor but are
significant when reading data from different machines.

When a RAW 16 bit format is loaded into memory, the operator must specify that
the data is either BIG or LITTLE endian to ensure that the byte order is
correct.  If a RAW format is loaded and it appears to be randomly garbled, try
loading it with a different order.


ΓòÉΓòÉΓòÉ 2.2.4.2.9. Comment ΓòÉΓòÉΓòÉ

Almost all sound formats support the inclusion of a string of text embedded in
the header of the file.  The comment field of the information display can be
used to change the comment when it is saved back to disk.  If a file is loaded
which does not contain a comment or a file is created with PMsndX, the default
comment of Edited by PMsndX is automatically created.


ΓòÉΓòÉΓòÉ 2.2.4.3. Full Graph ΓòÉΓòÉΓòÉ

One of the biggest problems with editing audio samples is the quantity of data
that even the smallest audio sample contains.  As an example, one second of
audio for a single channel at 11025 Hz contains over 10,000 samples of data.
When editing a sample, the actual position of the operations that are being
performed need a reference display to indicate a relative position within the
total sample. EdSndX provides this in the form of the Full Graph region.  This
graph displays the first channel of the sample along with the current audio
playback position, start of a range, and end of a range.  This display in
combination with the Horizontal Position bar below it provides enough
information to determine where the channel displays are within the scope of the
entire sample.

The full display is the primary point of reference for all editing operations.
The current playback position, the range, and even the level of zoom can be
affected by the full display.

The full display can be used to set the range of operation for the tools and
for the audio playback using the second mouse button to select either Start or
End in the full display.  By default, when a sample is loaded, the entire
sample is selected as indicated by the entire sample being displayed in the
light yellow color.

The full display can be used to set the PLAY position within the sample by
moving the mouse to the desired position and pressing the second mouse button.
This brings up a popup menu in which the operator may select Play Position. The
PLAY control window will be updated with the new play back position and a
vertical bar will be displayed.  During audio playback, this bar will move
across the display to provide a rough indicator of the current position of
playback within the sample.


ΓòÉΓòÉΓòÉ 2.2.4.4. Horizontal Position ΓòÉΓòÉΓòÉ

The Horizontal Position bar is directly below the full display graph and is
used to indicate the portion of the display which is viewable in the lower
channel displays. This bar operates much like a conventional scroll bar with
the exception that the range of the display is indicated by a simple line with
markers on the ends.

As indicated in the following figure, the width of the line for the horizonatal
position changes depending on the level of Zoom that has been selected.

When a zoom level other than MIN has been set, the horizonatal position can be
moved by either dragging the display to the position that is desired or by
clicking on either the buttons at the end of the display or by clicking on the
region to the left and right of the bar.  When the buttons are clicked, the
display moves 1/20 the width of the channel graph in the direction of the
button.  When the area to the left or right of the bar is selected, the display
moves 1/2 the width of the channel graph in the direction of the side selected.


ΓòÉΓòÉΓòÉ 2.2.4.5. Channel Graph ΓòÉΓòÉΓòÉ

EdSndX has the capability to display and edit either a single channel at a time
or all channels at once.  The following diagram shows the channel display when
a single channel is displayed.

When displaying a single channel of a sample, a vertical scroll bar appears to
the right of the display if the sample has more than one channel.  This scroll
bar is used to move between the individual channels.  When using the tools and
the checkbox for the selected channel is checked, the displayed channel in the
editor is the one that will be affected.

The following diagram shows the channel display when all channels are
displayed.

Notice that when this mode is set, all the channels of the smaple are displayed
in the same space that a single channel was displayed an the vertical scroll
bar is removed.  When in this mode, all tool operations will occur on all
channels of the sample.

The mode of operation to be used is stored in the .ini between each session.
Changes in mode are seen immediately. The channel display can be used in the
same way that the full display is used for selecting the play position and
range.  The area of the data displayed is indicated by the horizontal position
indicator below the full display.  The viewing region is indicated by the width
and position of the bar.


ΓòÉΓòÉΓòÉ 2.2.4.6. Controls ΓòÉΓòÉΓòÉ

EdSndX provides a control area where the status of the various regions are
displayed.  This area also provides a means to edit the information by either
double clicking on the entry with the first mouse button or by bringing up a
menu with the second mouse button.  The following fields are used to manipulate
the display.

 Start             Indicates/sets the start of the selected range
 End               Indicates/sets the end of the selected range
 Play              Indicates/sets the position to start playback and the mode
                   of playback operations
 Zoom              Indicates/sets the current zoom level and mode of operation
 Cursor            Indicates the current cursor position over the window and
                   sets starting point for the channel display
 Footnote          Displays a short string of text for the window under the
                   cursor
 Percent           Displays the progress of the current operation


ΓòÉΓòÉΓòÉ 2.2.4.6.1. Start ΓòÉΓòÉΓòÉ

The start window is used to display and set the start of the selected range.
When in the display mode, the start window displays the current start of the
selected range in either index or time format.

Double clicking the mouse on the window changes it to edit mode in which the
operator may enter the exact starting position.  Note that the information
entered must be in the same format as it was displayed.  If the value is
outside the range of the samples, the value will automatically be changed to
the nearest valid value.

Clicking on the window with the second mouse button pulls up a popup menu that
allows the user to select either Set..., Start, or Playpos. Selecting Set... is
the same as double clicking on the window which allows the field to be edited.
Selecting Start sets the start of the range to the beginning of the sample
(i.e. index 0 or time 0:0.0000). Selecting Playpos sets the start of the range
to the current play position (indicated by the PLAY window).


ΓòÉΓòÉΓòÉ 2.2.4.6.2. End ΓòÉΓòÉΓòÉ

The end window is used to display and set the end of the selected range.  When
in the display mode, the end window displays the current end of the selected
range in either index or time format.

Double clicking the mouse on the window changes it to edit mode in which the
operator may enter the exact ending position.  Note that the information
entered must be in the same format as it was displayed.  If the value is
outside the range of the samples, the value will automatically be changed to
the nearest valid value.

Clicking on the window with the second mouse button pulls up a popup menu that
allows the user to select either Set..., End, or Playpos Selecting Set... is
the same as double clicking on the window which allows the field to be edited.
Selecting End sets the end of the range to the end of the sample.  Selecting
Playpos sets the end of the range to the current play position (indicated by
the PLAY window).


ΓòÉΓòÉΓòÉ 2.2.4.6.3. Play ΓòÉΓòÉΓòÉ

The PLAY window is used to display and set the current play position or the
mode of operation.  When in the display mode, the current audio playback
position is displayed in either index or time format.  During playback through
the audio device, the PLAY window is updated to reflect the current position of
the playback.  Updates from the audio device occur about once every quarter of
a second to limit the overhead in displaying the position indicator in the
graphical windows. During playback, the graphical indicator for the play
position is only updated in the full display to limit system CPU requirements
as a result of updating the displays.

Double clicking the mouse on the window changes it to edit mode in  which the
operator may enter the exact position for audio playback to start.  Note that
the information entered must be in the same format as it is displayed.  If the
value is outside the range of the samples, the value will automatically be
changed to the nearest valid value.

Clicking on the window with the second mouse button pulls up a popup menu that
allows the user to select either Set..., Start, End, or Mode.  Selecting Set...
is the same as double clicking on the window which allows the field to be
edited.  Selecting Start sets the current playback position to the start of the
range.  Selecting End sets the current playback position to the end of the
range.  The mode item is used to select the mode of playback.


ΓòÉΓòÉΓòÉ 2.2.4.6.3.1. Play mode ΓòÉΓòÉΓòÉ

Selecting Mode allows the playback mode to be set to either Range or Playpos.
Setting the Play mode to Range causes playback to start at the beginning of the
selected range and automatically rewinds to that position whenever playback
stops.  Setting the Play mode to Play pos causes playback to start wherever the
current playpos marker is set and does not automatically rewind when playback
stops.


ΓòÉΓòÉΓòÉ 2.2.4.6.4. Zoom ΓòÉΓòÉΓòÉ

The zoom window is used to display and set the current zoom level.  When in the
display mode, the zoom window displays the current zoom level in the form of
1/zoom.  By default the zoom level is initially set to be the minimum zoom such
that the entire sample can be displayed in the channel display.  The zoom is
unique to the other controls in that it operates in modes which affect the way
the zoom is handled when the edit window is resized.

Double clicking the mouse on the window changes it to the edit mode in which
the operator may enter the exact zoom. Note that the information must be
entered in the same format as it is displayed.  If the value is outside the
range of valid values, the value will automatically be changed to the nearest
valid value.

Clicking on the window with the second mouse button pulls up a popup menu that
allows the user to select either Set..., Range, Min, or Max.

Selecting Set... is the same as double clicking on the window which allows the
field to be edited.  When the zoom level is set by editing the zoom value
directly, the set level remains fixed when the edit window is resized unless
the set zoom will result in a value which is outside the range of zoom values
for the sample.

Selecting Range sets the zoom level to the nearest integer which will display
the entire selected range in the channel display.  When the zoom level is set
to range mode, the current zoom changes whenever the window is resized or when
a new range is selected.  The object of this mode is to maintain the current
zoom value such that the range can fit within the channel display.  Note that
even though the window will maintain the correct zoom for the entire selected
range to fit within the window, the starting position of the left side of the
channel display will not be adjusted to keep the range actually displayed in
the channel display.  This allows the current viewing area to remain unchanged
after resizing.

Selecting Min sets the zoom level to the nearest integer which will display all
samples in the channel display.  When the zoom level is set to the min mode,
the zoom level is adjusted to ensure that all samples are displayed in the
channel display after the window is resized.

Selecting Max sets the zoom level to 1/1 which displays each sample exactly one
screen unit wide.  This zoom level is not affected by resize operations.


ΓòÉΓòÉΓòÉ 2.2.4.6.5. Cursor ΓòÉΓòÉΓòÉ

The cursor window is used to display the current position of the mouse cursor
as it moves across the data windows.  The cursor window is also used to set the
beginning of the channel display.  When in the display mode, the cursor
displays the current mouse position in either index or time format.

Double clicking the mouse on the window changes it to edit mode in which the
operator may enter the exact starting position of the channel display.  Note
that the information entered must be in the same format as it is displayed.  If
the value entered is not valid for the display zoom level, it is automatically
adjusted to the nearest valid value.

Clicking on the window with the second mouse button pulls up a popup menu that
allows the user to select either Set..., Start, End, or Play.  Selecting Set...
is the same as double clicking on the window which allows the field to be
edited.  Selecting start sets the left edge of the channel display to the
current start of the selected range. Selecting end sets the right edge of the
channel display to the current end of the selected range. Selecting play sets
the left edge of the channel display to the current play position.


ΓòÉΓòÉΓòÉ 2.2.4.6.6. Footnote ΓòÉΓòÉΓòÉ

The edit window has a small window which displays a short message indicating
something about the window directly under the cursor.  One of the particular
uses of this window is to monitor which channel is currently displayed when the
editor is set to display a single channel at a time.  The footnote window is a
permanent part of the edit window and is not affected by the footnote
properties settings for the main control panel.


ΓòÉΓòÉΓòÉ 2.2.4.6.7. Progress ΓòÉΓòÉΓòÉ

Any operation which launches a thread to perform the operation will provide
feedback to the operator to indicate the percentage of work that has been
completed through the progress window.  This window is composed of a colored
bar that moves to the right as the percentage increases. The window also
displays the numeric percentage in the middle of the windows.  Every edit
window has a percentage indicator which allows each editor to provide
indicators for operations which are associated with a single sample. This
iherently implies that the toolbox can launch threads for each editor
independently and simultaneously.

Note:  Some operations (e.g. the echo effect) launch multiple threads in series
       which cause the percentage indicator to seem to cycle.


ΓòÉΓòÉΓòÉ 2.2.4.7. Audio ΓòÉΓòÉΓòÉ

The audio region of the edit window is used to control access to the AUDIO
device.  Only one edit window can play or record audio and so all edit windows
are linked together such that when one is active, the others are disabled.  The
volume is the exception in that it is accessible at all times regardless of
whether the edit window is editing or not.

The following buttons are used:

 Record            Starts audio recording
 Stop              Stops audio operations
 Play              Starts audio playback
 Rewind            Rewinds audio position indicator
 Volume            Sets the volume for playback


ΓòÉΓòÉΓòÉ 2.2.4.7.1. Record ΓòÉΓòÉΓòÉ

The record button is used to start recording a sample.  The record button is
disabled until the settings for the recording have been established using the
Record Setup menu item.  After setting up the parameters, recording can start
immediately after the record button is pressed.  During the process of
recording, the operator may press the stop button at which point the recording
will stop and the new data will be displayed.  If the operator does not press
stop, the recording will continue until the set limit is reached.

Since the audio device is shared between all edit windows, when one is
recording, all buttons on the other windows are disabled.


ΓòÉΓòÉΓòÉ 2.2.4.7.2. Stop ΓòÉΓòÉΓòÉ

When audio playback or recording is active, the stop button for the edit window
which currently has access to the audio device is enabled.  This button allows
the operator to terminate the current audio operation.  If the editor is
playing the current sample, the play position indicator will remain at the last
sample played.  If the play mode is currently set for playpos playback will
continue where it left off if the play button is pressed.


ΓòÉΓòÉΓòÉ 2.2.4.7.3. Play ΓòÉΓòÉΓòÉ

The play button is used to start playback of the current sample from memory.
when this button is pressed, the start of the playback depends on the current
mode for playback.  When in the range mode, playback will automatically start
at the beginning of the current selected range regardless of the Play
indicator.  When in playpos mode, playback will automatically start at the
current position indicated by the PLAY window.

There is no pause button because the playback can be set to start where it left
off by setting the mode to playpos.  The range mode is designed for use when a
particular area is being edited and the operator wants to play a particular
range over a number of times without having to stop the playback with the stop
button.  Additionally, either mode can be useful when the playback is set to
automatically repeat repeat.

The play button also serves to provide an indication as to the status of the
audio buffers.  Whenever a sample is changed, the editor may start loading the
audio buffers immediately depending on the setting of the Delay AUDIO Loading.
When the task for loading the buffers is operating, the word Loading will be
displayed at the bottom of the button and the button will be disabled.  Once
the buffers have been loaded, the button will be enabled if the audio device is
not in use by another edit window.


ΓòÉΓòÉΓòÉ 2.2.4.7.4. Rewind ΓòÉΓòÉΓòÉ

When the rewind button is pressed, the PLAY window is reset to the either the
beginning of the selected range or to the beginning of the sample depending on
the current mode of playback.  If the current PLAY position is already at the
beginning of the range or sample, the rewind button is disabled.


ΓòÉΓòÉΓòÉ 2.2.4.7.5. Volume ΓòÉΓòÉΓòÉ

Of the audio controls on the edit window, the volume display is the only one
that is active at all times.  The audio display is shared across all edit
windows simultaneously such that changes in one window are reflected in all
open windows.  The volume control is a sliding bar which sets the volume to a
percentage of the maximum volume for the audio card.  This volume is different
from the volume effect in the toolbox in that it does not affect the actual
samples; rather, it affects the audio device.

The volume control is similar to a standard slider except that it does not have
an associated button.  Rather, it is like an analog volume control such that
the slider moves to the right and left using the mouse and the width of the
slider indicates the volume.  Additionally, the actual percentage of the volume
is indicated in the display for convenience.

The slider may be moved using the mouse button or the normal keys associated
with scroll bars.  By selecting the area near the edge of the sliding portion
of the control, the slider can be captured and the mouse can be used to drag
the volume to the desired position.  If playback is occurring, the effect is
immediately heard.  The area to the left or right of the slider edge may also
be selected with the first mouse button to move the slider one percent up or
down depending on the position that is selected.  Holding the mouse down causes
the slider to increase at a rate of about 1 percent per tenth of a second.
Finally, the second mouse button may be used to move the slider to a specific
position quickly.


ΓòÉΓòÉΓòÉ 2.2.5. Menu Bar ΓòÉΓòÉΓòÉ

All of the functions of the editor are accessible through the menu bar.  Popup
menus for various windows are duplicates of entries from the main menu bar.  As
a result, menus which are checked in the popup menus are reflected in the main
menu bar.


ΓòÉΓòÉΓòÉ 2.2.5.1. File ΓòÉΓòÉΓòÉ

The File menu is used to access functions which will result in IO operations
such as disk access, printing, or recording.  The following items are
accessible from this menu:

 New               Displays a list of open files and switches focus
 New               Creates a new (empth) edit window
 Open              Opens a file for editing in another edit window
 Save              Saves the current data to disk using the current filename
 Save As           Saves the current data to disk using a different filename
 Print             Prints information about the sample to a printer
 Print Setup       Sets up the format of the data to be printed
 Record setup      Sets up parameters required to record data from the audio
                   device


ΓòÉΓòÉΓòÉ 2.2.5.1.1. File List ΓòÉΓòÉΓòÉ

From every edit window, a list open files can be found under the File List menu
item.  Selecting any of the files in the list switches the focus to that editor
window. This list of files performs the same functions as the list from the
main control panel's system menu.


ΓòÉΓòÉΓòÉ 2.2.5.1.2. New ΓòÉΓòÉΓòÉ

The New menu item can be used to create a new sample editing window.  This has
the same effect as pressing the New button on the control panel.


ΓòÉΓòÉΓòÉ 2.2.5.1.3. Open ΓòÉΓòÉΓòÉ

The Open menu item can be used to open an existing file for editing.  This has
the same effect as pressing the Open button on the control panel.


ΓòÉΓòÉΓòÉ 2.2.5.1.4. Save ΓòÉΓòÉΓòÉ

Once a file has been edited, it can be saved to disk for permanent storage.  If
the file has already been named, its name will appear in the titlebar of the
editor and will automatically be saved as that name.  If the file has not been
named yet, the Save As... dialog box will automatically be used to save the
file to force the operator to name the file.


ΓòÉΓòÉΓòÉ 2.2.5.1.5. Save As.. ΓòÉΓòÉΓòÉ

The following diagram illustrates the Save As... dialog.

The Save As... menu item is used to save a file to a different file name than
is displayed in the titlebar of the edit window.  The Save As... menu item can
also be used to change the type of the file to be saved using the FORMAT field
of the dialog.

The Save As... dialog is identical to the Open dialog with the exception that
it is associated with a particular edit window and multiple copies of the Save
As... dialog can be displayed at the same time.


ΓòÉΓòÉΓòÉ 2.2.5.1.6. Print ΓòÉΓòÉΓòÉ

Not implemented in this revision.


ΓòÉΓòÉΓòÉ 2.2.5.1.7. Print Setup ΓòÉΓòÉΓòÉ

Not implemented in this revision.


ΓòÉΓòÉΓòÉ 2.2.5.1.8. Record Setup ΓòÉΓòÉΓòÉ

In order to record a sample from the audio device, the parameters for the
recording must be set up.  The following illustration shows the dialog that is
used to set up a recording.

This dialog box is used to set the recording parameters for the AUDIO group of
EdSndX.  Changes made to this dialog are saved between sessions but it is
necessary to open this dialog to set up the parameters for the recording for
each individual edit window.  When the Record Options dialog is opened, EdSndX
tests the audio adapter and only enables the features which are supported by
the adapter.

EdSndX records all audio directly to memory; consequently, the most important
control for recording is the limit to the amount of memory in which the data is
stored.  The limit on the memory requirements for recording audio is displayed
and changed in three different ways.  The first is to specify the amount of
time for recording, the second is to specify the number of samples, and the
third is to specify the amount of memory.  Changes to each of the entry fields
automatically updates the other fields when the focus is changed.  The limit is
stored internally as the number of samples to be recorded.  For this reason,
changes to the rate, quality, and channels affects the time and memory
requirements to record the sample.  These options should be set before
establishing the limits.

Note:  The memory limit field specifies the amount of raw memory required to
       hold the recorded data and is synonymous with the amount of data that
       would be stored in a .WAV file. This limit should not be confused with
       the internal memory requirements of PMsndX. After the recording has been
       made, the data will be converted to the internal format.

 The selections made in the Record Options dialog must be applied before the
 dialog is dismissed.  Otherwise, the recording options automatically revert to
 whatever was last applied.  When the Record Options  dialog is dismissed the
 necessary memory is allocated and the editor is set up to prepare for
 recording. If the Undo property box has been enabled the previous sample may
 be restored using the Undo menu item.

 Note:  The CD selection is disabled in this version.  Reading an AUDIO CD is
        more complicated than the normal input ports. I have not figured out
        how to make the MCI_AMP_SET_MONITOR work on my SB16.  Setting or
        clearing Monitor Input has no effect on my system.  If it does
        something for you, then let me know.  I know what it is suppose to do.


ΓòÉΓòÉΓòÉ 2.2.5.2. Edit ΓòÉΓòÉΓòÉ

The items under the Edit menu are used to cut and paste samples using the
clipboard and for performing functions normally necessary to prepare a sample
for editing.  The following items are available through the Edit menu:

 Undo              Undo the last operation
 Cut               Cut the current selection to the clipboard
 Copy              Copy the current selection to the clipboard
 Merge             Merge data from the clipboard into the current sample
 Merge from        Merge data from another edit window into the current sample
 Paste             Paste data from the clipboard into the current sample
 Paste from        Paste data from another edit window into the current sample
 Clear clipboard   Clear the clipboard
 Select all        Select all data in the current sample
 Zero region       Set all data in the selected range to zero
 Remove region     Deletes the data in the current range from the sample


ΓòÉΓòÉΓòÉ 2.2.5.2.1. Undo ΓòÉΓòÉΓòÉ

If the Undo property is checked, any changes to a sample are buffered such that
any single change can be undone.  This feature is only available when the
program has been registered.

The Undo feature maintains a buffer for exactly one change such that if the
Undo menu is selected twice in a row, the net effect is to leave the editor
unchanged because the second use of the Undo is essentially the same as the
redo.  In actuality, all the Undo does is to swap the previous buffer with the
present buffer.


ΓòÉΓòÉΓòÉ 2.2.5.2.2. Cut ΓòÉΓòÉΓòÉ

Rules for cut:

The CUT feature is used to cut data out of the current sample and place it on
the clipboard.  When this operation is performed, the new data replaces any
data that already exists on the clipboard.  The CUT operation adheres to two
rules.

1.  If all channels are displayed, then copy all of the data over the specified
interval and shift all data over to the left.

2.  If a single channel is displayed, then copy the data over the specified
interval for that single channel to the clipboard, and shift the data after the
interval over to the left while clearing the end of the data for the specified
channel.


ΓòÉΓòÉΓòÉ 2.2.5.2.3. Copy ΓòÉΓòÉΓòÉ

The Copy operation copies all of the data selected in a range to the clipboard
in a format which is compatible with the Digital Audio Tool distributed with
the OS/2 operating system.

The copy operation copies the currently displayed range and channels to the
clipboard so the operator must be careful to display either the correct channel
or all channels before selecting the copy operation.

Note:  When PMsndX is not registered, ranges cannot be used for the copy
       operation.


ΓòÉΓòÉΓòÉ 2.2.5.2.4. Merge ΓòÉΓòÉΓòÉ

When the MERGE button is pushed, the editor will merge the data from the
clipboard with the data in memory.

The merge operation varies depending on the number of channels in the current
sample and the number of samples in the data on the clipboard. After the merge
operation, the start marker will remain unchanged.

1.  If there is no current data, then just copy the clipboard directly to
memory.

2.  If the number of merged channels is the same as the current data, then
merge the data in based on the selected channel for manipulation.

Note:  When merging, the data is averaged based on the selected channel for
       manipulation.  Any excess difference between the length of the two will
       be left unafffected.

 3.  If the number of merged channels is 1, then average the data from the
 clipboard to the channel(s) selected for manipulation.  If the length of the
 samples does not match the data will be averaged for the common length of the
 two and excess will not be modified.

 4.  If the number of merged channels is less than the current number of
 channels (but greater than 1), then

 a) average the data from the clipboard directly into the current sample and
 leave the non-existent channels unaffected.

 b) average the first channel from the clipboard with the selected channel for
 manipulation.

 5.  If the merged sample has more channels than the current sample, then

 a) average the existing channels and copy the clipboard data directly to the
 channels that did not exist in memory.

 b) the first channel is merged into the selected channel for manipulation.

 6.  If all of this fails, then just warn the user and give up.


ΓòÉΓòÉΓòÉ 2.2.5.2.5. Merge From ΓòÉΓòÉΓòÉ

When more than one edit window is open, EdSndX provides the capability to merge
data from one editor to another without going through the clipboard.  The Merge
From menu item is only activated when more than one edit window is open and the
submenu is filled with the filenames of the other edit windows in the same
format as that used in the File List accessed from the main menu.

When merging from another edit window, the same rules apply as do for the
clipboard merge operations as if the range selected were copied to the
clipboard.  The advantage of merging between edit windows without using the
clipboard is that it is faster and does not require the creation of temporary
buffers.

Note:  If PMsndX is not registered, the merge from function does not recognize
       the range selected and will always copy all samples and channels as if
       the enter sample were copied to the clipboard.


ΓòÉΓòÉΓòÉ 2.2.5.2.6. Paste ΓòÉΓòÉΓòÉ

Rules for paste:

The PASTE button is used the paste the contents of the clipboard into memory.

The paste operation varies depending on the number of channels in the current
sample and the number of samples in the data on the clipboard. After the paste
operation, the start marker will be set at the beginning of the sample pasted
from the clipboard and the end marker will be set to the end of the new data.

1.  If there is no current data, then just copy the clipboard directly to
memory.

2.  If the number of pasted channels is the same as the current data, then past
the data in based on the selected channel for manipulation.

3.  If the number of pasted channels is 1, then just copy the data to the
channel(s) selected for manipulation and insert blank space for the
corresponding channels which are not being manipulated.  If the number of
channels for manipulation is "ALL" then duplicate the data for the single
channel across all channels of the current data.

4.  If the number of pasted channels is less than the current number of
channels (but greater than 1), then

a) if the channels selected for manipulation is set to "ALL" then copy the
channels from the clipboard directly into the current sample and zero out the
non-existent channels.

b) copy the first channel from the pasted sample into the selected channel for
manipulation.

5.  If the pasted sample has more channels than the current sample, then

a) if the channels selected for manipulation is set to "ALL" then create the
new channels in the existing data and set all non-existent channels in the
existing data to zero.

b) copy the first channel from the pasted sample into the selected channel for
manipulation.

6.  If all of this fails, then just warn the user and give up.


ΓòÉΓòÉΓòÉ 2.2.5.2.7. Paste From ΓòÉΓòÉΓòÉ

When more than one edit window is open, EdSndX provides the capability to paste
data from one editor to another without going through the clipboard.  The Paste
From menu item is only activated when more than one edit window is open and the
submenu is filled with the filenames of the other edit windows in the same
format as that used in the File List accessed from the main menu.

When pasting from another edit window, the same rules apply as do for the
clipboard paste operations as if the range that is currently selected were
copied to the clipboard. The advantage of pasting between edit windows without
using the clipboard is that it is faster and does not require the creation of
temporary buffers.

Note:  If PMsndX is not registered, the paste from function does not recognize
       the range selected and will always copy all samples and channels as if
       the enter sample were copied to the clipboard.


ΓòÉΓòÉΓòÉ 2.2.5.2.8. Clear Clipboard ΓòÉΓòÉΓòÉ

The Clear Clipboard function is provided to reduce the memory requirements
during the process of editing.  When data is copied to the clipboard, it is
allocated by an application and then passed to the clipboard system of OS/2.
As long as the data remains on the clipboard, the memory is reserved and
unusable to other applications.  Freeing this memory reduces the impact on the
overall memory resources for the system.

Rules for Clear operation:

This operation clears all data from the clipboard.  It has no effect on data
currently in memory.


ΓòÉΓòÉΓòÉ 2.2.5.2.9. Select All ΓòÉΓòÉΓòÉ

Use this menu item to select the entire sample such that the start of the range
of selection is set to 0 and the end of the range is set to the end of the
sample.


ΓòÉΓòÉΓòÉ 2.2.5.2.10. Zero Region ΓòÉΓòÉΓòÉ

Rules for Zero operation:

Set the data over the specified interval to 0 for the channels specified.


ΓòÉΓòÉΓòÉ 2.2.5.2.11. Remove Region ΓòÉΓòÉΓòÉ

Rules for Remove operation:

1.  If all channels are displayed, then remove the data over the specified
range for all channels and shift all data to the left.

2.  If a single channel is displayed, then remove the data for that channel
over the specified range and shift the end of that channel to the left while
zeroing out the end of the channel.


ΓòÉΓòÉΓòÉ 2.2.5.3. Options ΓòÉΓòÉΓòÉ

The editor window utilizes a set of options that are specific to the window and
which are stored between sessions.  These settings are shared between editor
windows such that changes in one window affect all other windows. These options
are also accessible through the editor properties page of the properties box.

The following menu items are available under this menu.

 Display Info      Toggles the information display in the edit window
 All channels      Toggles the display of one or all channnels
 Delay AUDIO loading Toggles the automatic loading of the audio buffers
 Load AUDIO at playback Toggles the automatic loading of the audio buffers when
                   the play button is pressed
 Load AUDIO Data Now Forces audio data to be loaded immediately
 Auto repeat       Toggles audio playback repeat
 Format            Toggles the method for displaying sample indexes


ΓòÉΓòÉΓòÉ 2.2.5.3.1. Display Info ΓòÉΓòÉΓòÉ

The information display at the top of the edit window is optional.  By default,
the information display is present on all edit windows but may be toggled by
selecting this menu item.  When this display is not present, the graphical
displays are automatically expanded to fill the space.


ΓòÉΓòÉΓòÉ 2.2.5.3.2. All Channels ΓòÉΓòÉΓòÉ

The individual channel display can be set to either display all channels at
once or a single channel at a time.  When all channels are displayed, all
channels of a sample share the same space that would normally be used to
display a single channel.

By default, all channels are displayed for a sample unless the check is cleared
by toggling this menu item.


ΓòÉΓòÉΓòÉ 2.2.5.3.3. Delay Audio Loading ΓòÉΓòÉΓòÉ

One of the problems with sound samples is that they take up a large amount of
memory.  This is compounded by the way that EdSndX maintains a sample as 16 bit
data regardless of the type of data required to store the samples.  In order to
play samples through the audio, the edit window can automatically load the
necessary buffers for audio playback.

By default, each editor reloads the buffers whenever the sample is changed.
This not only takes up extra CPU resources, but it can add to the memory
requirements of the program.  If memory is tight and the swap file is being
used, toggle this menu item to prevent taking up the memory to buffer for the
audio device.  When this is selected, the Load Audio at Playback item is
enabled.  Use the Load Audio Data Now menu item to load the audio buffers when
ready to play data.

This option has been provided to allow the operator to weigh the effects of
maintaining audio buffers.  If the buffers are not automatically loaded, then
there will be a delay whenever audio playback is requested as the buffers are
loaded.  If the buffers are automatically loaded, then the extra memory
requirements must be tolerated.


ΓòÉΓòÉΓòÉ 2.2.5.3.4. Load Audio At Playback ΓòÉΓòÉΓòÉ

This menu item is only enabled when Delay Audio Loading has been selected.
When this feature is enabled, the play button is enabled but the buffers are
not loaded when samples are changed; however, the audio buffers are
automatically loaded when the playback button is pressed.  When this feature is
disabled, the playback button will not be enabled until the Load Audio Data Now
has been selected to force the buffers to be loaded.


ΓòÉΓòÉΓòÉ 2.2.5.3.5. Load Audio Data Now ΓòÉΓòÉΓòÉ

This menu item is always enabled to allow the operator to force EdSndX to
reload the audio buffers at any time. Normally, EdSndX will reload the buffers
whenever the sample is changed; however, when Delay Audio Loading has been
enabled, the operator will need to select this menu item to load the buffers
for playback unless Load Audio at Playback has been enabled.


ΓòÉΓòÉΓòÉ 2.2.5.3.6. Auto Repeat ΓòÉΓòÉΓòÉ

This menu item is used to toggle the ability of the editor to automatically
rewind the playback and restart whenever the audio playback reaches the end of
the sample.  By deafult, this feature is disabled.


ΓòÉΓòÉΓòÉ 2.2.5.3.7. Format ΓòÉΓòÉΓòÉ

EdSndX has the capability to display index references in the form of either a
sample index or as a time index.  This menu item has two submenu items for each
display method.  When the time format is used, all index references are
displayed in the form of MM:SS.HHHH and all data entered by the user when
editing index fields is expected to be entered in this format.  When in sample
index mode, the index is displayed as an integer which represents the physical
sample offset within a channel.

The default for this feature is to display all indexes in the time format.


ΓòÉΓòÉΓòÉ 2.2.5.4. Display ΓòÉΓòÉΓòÉ

This menu provides access to management of the display to let the operator move
the displays using different references and to control the zoom level of the
display.

The following menu items are available for the display.

 Goto              Sets the start/end of the displays
 Zoom              Sets the method for zooming in on data
 Redraw            Forces the entire edit window and all fields to be redrawn


ΓòÉΓòÉΓòÉ 2.2.5.4.1. Goto ΓòÉΓòÉΓòÉ

The Goto submenu allows the operator to select the starting point of the
individual channel display. This has the same effect as moving the display
position slider bar with the mouse and is subject to the same limitations as
the display position bar however, this submenu provides quick access to
frequently used positions.

See cursor region for a description of the popup menu which is identical in
function to this submenu.


ΓòÉΓòÉΓòÉ 2.2.5.4.2. Zoom ΓòÉΓòÉΓòÉ

The Zoom menu is used to manipulate the method for zooming in on the data.  The
method for zooming in on a sample affects the way the edit window reacts to
resizing.

See zoom region for a description of the popup menu which is identical in
function to this submenu.


ΓòÉΓòÉΓòÉ 2.2.5.4.3. Redraw ΓòÉΓòÉΓòÉ

In the event that the operator feels that the edit display is out of sync, the
Redraw menu item can be used to force the editor to update all displays.


ΓòÉΓòÉΓòÉ 2.2.5.5. Markers ΓòÉΓòÉΓòÉ

Markers are used as indicators of important positions in a sample.  These
markers can be simply used for information to the operator or to allow the
operator to provide key positions which are used to manipulate the sample.

The following marker menu items are provided in this menu.

 Start             Sets the starting point for range selection
 End               Sets the ending point for range selection
 Play              Sets the current playback position


ΓòÉΓòÉΓòÉ 2.2.5.5.1. Start ΓòÉΓòÉΓòÉ

The Start submenu is used to select the start of the selection range.  See
start region for a description of the popup menu which is identical in function
to this submenu.


ΓòÉΓòÉΓòÉ 2.2.5.5.2. End ΓòÉΓòÉΓòÉ

The End submenu is used to select the end of the selection range.  See end
region for a description of the popup menu which is identical in function to
this submenu.


ΓòÉΓòÉΓòÉ 2.2.5.5.3. Play ΓòÉΓòÉΓòÉ

The Play submenu is used to select the current position of audio playback.  See
play mode for a description of the popup menu which is identical in function to
this submenu.


ΓòÉΓòÉΓòÉ 2.2.5.6. Tools ΓòÉΓòÉΓòÉ

The DSP tools have been disassociated from individual samples and edit windows
by providing the DSP tools in the form of a toolbox. In order to utilize the
DSP tools, the edit window provides a menu which allows the user to temporarily
associate the toolbox with an edit window.

The tools menu provides the following special items.

 Abort             Aborts the current DSP tool
 Switch to         Opens the toolbox and associates the current edit window
                   with the toolbox

 Other items are available which correspond to the pages of the toolbox and can
 be used to automatically switch to a page and associate the toolbox with the
 edit window in one step.


ΓòÉΓòÉΓòÉ 2.2.5.6.1. Abort ΓòÉΓòÉΓòÉ

The operation of the toolbox is to become temporarily associated with the
editor window such that a tool can be setup and then launched.  Upon starting
the task to perform a DSP tool, the toolbox automatically disassociates itself
from the edit window.  As a result, the edit window maintains ownership of the
task which is performing the DSP function and has to have a means to abort the
operation. At any time before the progress indicator on the edit window reaches
99%, the Abort button is enabled and will allow the operator to terminate the
current DSP thread for that editor.  When a DSP thread is not running, the
Abort menu item is disabled.


ΓòÉΓòÉΓòÉ 2.2.5.6.2. Switch To ΓòÉΓòÉΓòÉ

As indicated, the toolbox is disassociated from the edit samples and edit
windows.  In order to use the toolbox, it must be temporarily associated with a
editor.  This is done by either using the switch to menu item or by selecting
the specific DSP tool to be used.

Regardless of the method, the toolbox displays the name of the sample that it
is currently assocaiated with in the titlebar of the toolbox.  When the switch
to menu item is selected, the toolbox is then changed over to the editor from
which the command came from.  In this manner, the toolbox can float between
each of the samples or be dismissed while the DSP operations are occurring.

If the toolbox is not displayed at the time that the association is requested,
EdSndX will automatically display the toolbox.


ΓòÉΓòÉΓòÉ 2.3. Tools ΓòÉΓòÉΓòÉ

Using a notebook to display the TOOLS has some unique presentation advantages.
Primarily the notebook allows the effects to be displayed in a single dialog
window.  Since each effect is mutually exclusive of any other tool this
approach displays the maximum information that the user can utilize at any
time.  Another approach would have been to develop a dialog box for each tool.
This approach has the disadvantage that it would require a second control panel
to select the specific tools.  This would violate the approach of providing a
single control panel for the user and would necessitate managing a number of
different windows which could potentially clutter the screen.  The notebook is
a clean and aesthetically pleasing means for managing the tools.

The heart of manipulating the samples is accessed from the TOOLS notebook.
Some of the pages of the notebook provide information while others let the user
apply a particular effect on the current sound sample.  The TOOLS notebook can
be dismissed by pressing the TOOLS button on the main control panel or by
pulling down the system menu for the toolbox and selecting CLOSE.

The notebook is divided into sections such that functions with similar
operations are grouped together.  The tabs on the right of the notebook access
the section and the tabs at the bottom of the page are used to access the
individual functions of the grouping. The tabs on the notebook provide access
to the Info, Type, Average, Duplicate, Band Pass, Low Pass, Rate, Speed, Echo,
Invert, Reverse, Vibro, Limit, Fade, and Balance functions for manipulating the
samples.

The notebook may be navigated by either selecting the tab on the right of the
book for the desired function or by using the small Plus and Minus buttons at
the bottom of the notebook.  Using the Plus and Minus buttons will move through
the notebook a single page at a time.

To select the tabs using the keyboard, the focus for the notebook must be set
for the notebook container (by clicking the mouse outside of one of the tools
or by pressing the ALT key and the UP arrow). Selecting any character that is
underlined will bring that page to the top of the display.

The notebook can be displayed regardless of the presence of sample data in
memory.  When no sample is present, the pages of the notebook will be
invalidated but can still be viewed.


ΓòÉΓòÉΓòÉ 2.3.1. Info ΓòÉΓòÉΓòÉ

The Info page displays all of the relevant information about the samples
currently in memory.  This includes the following categories:

 Load Format     One of the formats which the program can save or open
 Data Type       The default extension for this file format.
 Data Style      SIGNED, UNSIGNED, ULAW, or ALAW
 Channels        Number of channels in the sample
 Sampling Rate   The number of samples taken each second
 Data Size       BYTE (8 bits), WORD (16 bits), LONG (32 bits)
 Samples         The number of samples that make up each channel
 Comments        Some sample files may contain comments.  Any comments found
                 are displayed in this window
 Byte Order      The natural order of the bytes in each sample.  This field can
                 display either Big Endian or Little Endian


ΓòÉΓòÉΓòÉ 2.3.2. Type ΓòÉΓòÉΓòÉ

The type of the file is determined by the header written to the beginning of
the file.  See Save for information how the file type is determined when a file
is saved to disk.  Additionally, the user may use the this tool to change the
Load Format (displayed in the Info page of the tools notebook).  When the file
is saved, the default file format will automatically be set to whatever has
been chosen on this page of the notebook.  Changing the file name extension or
selecting a file format in the SAVE dialog will override this setting.

Each file format utilizes different headers for the actual data.  By selecting
one of the standard formats on this page the Info page will show the user how
the samples will be saved.  The fields that are most likely to change are the
Load Format, Data Type, Data Style, and Data Size.


ΓòÉΓòÉΓòÉ 2.3.3. Average ΓòÉΓòÉΓòÉ

This tool is useful for reducing the number of channels in a sample by either
eliminating channels or by averaging the sounds together.  A sample with an
even number of channels may be averaged to produce a sample with half the
initial number of channels. For example, a sample with four channels can be
averaged to produce a sample with two channels and a sample with two samples
can be averaged to produce a sample with one channel.

Channels may be averaged in three ways.  The simplest is to take the left or
right channel data as the final data.  A more complex method is to average the
samples of the left and right to produce a center sample. The results of these
operations are significantly different and can result in very different output
samples.

When a sample contains four channels, it is composed of four sound sources at
45 degrees in each quadrant.  This corresponds to the Front Left, Front Right,
Rear Left, or Rear Right.  To average these into two channels the user can
select to use any of the four channels or to average based on the left or
right. To select or average any combination of the channels into either of the
output channels, check the box for the channels from the source sample.  To aid
in this, two radio buttons have been provided which enable or disable the
selection of check boxes in the second channel depending on the number of
output channels selected.


ΓòÉΓòÉΓòÉ 2.3.4. Dupe ΓòÉΓòÉΓòÉ

 This tool is useful to add channels to a sample through simple duplication.
When this tool is used, the new channels created are exact duplicates of the
original samples. Channels can be duplicated such that a single channel sample
can be made to have two channels which are identical or two channels can be
duplicated to form four channels.

When copying two channels to 4, PMsndX allows the user to specify which of the
input channels will be placed on the output channels.  In this way, a single
channel of a dual channel sample can be copied to any of the four output
channels.


ΓòÉΓòÉΓòÉ 2.3.5. Band Pass ΓòÉΓòÉΓòÉ

This tool provides the ability to apply a band-pass filter to a sample. A
band-pass filter is used to eliminate unwanted frequencies from a sample.  This
is often to eliminate high frequency hiss and low frequency hum from a sample.
The typical range of frequencies that affect the human ear are from about 100
Hz through about 16 kHz.  Like the equalizer on a stereo, the bandpass filter
can be used to reduce the effect of unwanted frequencies.  Although we
generally think of a bandpass filter as operating like a perfect step function,
it has ringing at the edges of the transitions and will affect the frequencies
near the edges of the filter.

The frequency response for the filter is designed to drop logarithmically
around a center frequency.  The slope of the drop at the desired start (Wp) and
end (Ws) of the filter varies with the distance between the Wp and Ws.  This
width is used to determine the slope of the dropoff at the edges of the filter.
The frequencies at Wp and Ws will be approximately half of their original
amplitudes and all frequencies outside of the Center - Wp and the Center + Ws
will be eliminated.  The bandpass filter can be mode oriented to pitched
signals (i.e. voice, singing, or instrumental music) or can be modified by
adding noise to the filter so that un-pitched signals can be effectively
processed.

Note:  To aid the user in locating the maximum effective center frequency, a
       light blue vertical bar is placed at half the sampling rate for the
       data.

  The transformation for the Bandpass filter was derived from a a program
 called MUSIC56K (as documented in the MUSIC56K source code) and implemented in
 C++ for this program.

 Operation of the bandpass filter tool is probably one of the most complex
 interfaces in the toolbox.  It is based on a simple principle.  The entire
 display of the filter represents the frequency response of the filter and is
 operated like a slider.  However, since the Start frequency and the Stop
 frequency are independent, the sliding bar is divided into identical controls
 for each filter edge. Before getting into the operation of the controls the
 display needs to be explained to establish the terms that will be used.

 As mentioned, the display is designed to illustrate the frequency response of
 the bandpass filter (independent of any added noise).  The center of the Start
 (Wp) and End (Ws) of the filter are marked by vertical BLUE bars.  The Center
 (Wc) of the filter is marked by a vertical RED bar.  These three markers
 provide the means for the user to modify the filter.  The region to the left
 of the RED center frequency is always the start of the filter.  The user may
 click the mouse to the left of Wp to decrease Wp by 1000 Hz.  Clicking between
 Wp and Wc increases Wp by 1000 Hz.  Likewise, clicking between Wc and Ws
 decreases Ws by 1000 Hz and clicking to the right of Ws increases Ws by 1000
 Hz.  The user may also click the mouse near Ws or Wp to drag the respective
 ends of the filter quickly.

 To provide fine control of the filter, Right and Left arrows are provided for
 both Wp and Ws.  Clicking on either the right or left arrow will increase the
 indicated filter edge by 1 Hz.  To increase or decrease the filter edges by 10
 Hz, the user may select the plus or minus corresponding to the filter edges.
 The left set of controls affects Wp and the right set of controls affects Ws.

 As the mouse is used to adjust Wp and Ws, the exact frequencies for Wp, Ws,
 Wc, and the filter Width are updated in the text input fields.  The user can
 use the mouse to select one of the input fields and modify it directly.  To
 accept a value in the entry field and recalculated the dependent frequencies
 select another window or click on another item which moves the focus from the
 notebook.  The rules for the fields are as follows:

   1. If the Center frequency is modified, new values for Wp and Ws are
      immediately calculated using the current Width. If Wp or Ws are outside
      of the possible ranges, then Wp or Ws are set to the limit of the
      acceptable range and the Width and Center are recalculated.
   2. If the Width of the filter is modified, new values for Wp and Ws are
      immediately calculated using the current Center frequency.  If Wp or Ws
      are then outside of the acceptable ranges, Wp or Ws is then set to its
      limit and the Center and Width are recalculated.
   3. If Wp is changed, the Width and Center are automatically recalculated to
      reflect the new start of the filter.
   4. If Ws is changed, the Width and Center are automatically recalculated to
      reflect the new end of the filter.

 The bandpass filter has been selected because of the desirable effect on
 typical sounds that will be processed by PMsndX such as voice or music.
 However, if other types of noise are to be filtered, noise can be added to the
 filter which results in a sharper peak of the filter.  To add this noise,
 select the checkbox for "Add filter noise". Selecting the checkbox again will
 disable the filter noise.

 Note:  The display of the frequency response for the filter does not reflect
        added noise.


ΓòÉΓòÉΓòÉ 2.3.6. Low Pass ΓòÉΓòÉΓòÉ

A Low Pass filter can be applied to a sample to eliminate high frequencies.
With a bandpass filter, it is not possible to eliminate any effect on lower
frequencies; however, a lowpass is designed specifically to eliminate changes
on frequencies below the right dropoff.  A lowpass filter is normally used to
eliminate high frequency hiss. Frequencies near the edge of the filter will be
attenuated by the natural change in the frequency response of the filter and
the ringing that occurs at the edge of the drop. The lowpass filter also
increases the volume of the sample and a attenuation (gain) factor is provided
to allow the user to limit the effect.  Depending on the volume of the initial
sample, the attenuation may be less important but should be experiemented with
to find a good compromise.

Filtering is accomplished in the digital domain through the use of a very
simple second order digital Fourier transform.  Future implementation may have
a more complex Fourier transform; however, the chosen function is desirable
because it provides a smooth dropoff without significant ringing. The
performance of the filter is determined by the cutoff frequency and the rate of
drop.  If the dropoff is made too quickly, the filter will exhibit a ringing
effect at the begin and end of the dropoff.  If the dropoff is performed too
slowly, the filter will suppress more frequencies toward the end of the desired
range.  The more orders of the filter (more stages), the better the frequency
response; however, more orders increase the time for filtering significantly. A
two order filter works adequately.

When performing the digital convolution of the sample with the step function a
Gain factor is used to normalize the output data.  This acts as a Volume
control for the sample to prevent losses due to numerical overflow.  Values for
the gain range from 0 to 1 in increments of 0.01.  A slider bar is used to set
the gain of the low pass filter.  When the low pass filter is first brought up,
the Gain will default to a value of 0.8.  If this is changed, it will remain at
the new setting until the session is terminated.

The Frequency response of the low pass filter is determined by a the
centerpoint of the dropoff at the end of the step function.  When performing a
digital filter, it is not possible to prevent the gradual drop at the end of
the step function due to the convolution of the samples used in the
transformation.  This is true for analog components also. The centerpoint of
the dropoff can be set in three ways. The user may enter the specific frequency
in the text entry box in the lower right corner or may use the filter display
like a sliding bar.  As is typical of a sliding bar, the mouse may be used to
capture the cutoff frequency by pressing the mouse button while the mouse is
near the cutoff frequency.  By holding the button down, the user may drag the
frequency to the desired range.  Additionally, the user may click to the right
or the left of the frequency cutoff to increase or decrease the frequency by
1000 Hz. The right and left arrows in the corners of the display may be used to
increase or decrease the frequency by 1 Hz. The plus and minus buttons in the
corners of the display may be used to increase or decrease the frequency by 10
Hz. The frequency response curve illustrates the dropoff that occurs at the end
of the step function.


ΓòÉΓòÉΓòÉ 2.3.7. Rate ΓòÉΓòÉΓòÉ

Every sound file is produced by sampling an analog wave at a specific
frequency.  As a result, the sound must be played back at the same frequency in
order for it to be reproduced clearly.  Higher sampling frequencies result in
better quality sound but increases the size of the file.  Most PC based sound
cards are designed to operate most effectively at multiples of 11025 Hz;
unfortunately, many sound files are sampled at rates which are not multiples of
11025 Hz and they can be resampled to be playable by applications which cannot
play these rates.  A drawback of sampling is that it may degrade the actual
samples because it must interpolate (predict) the original analog waveform
which introduces slight errors.  In most cases, this will not be
distinguishable by the human ear.

Once a sample has been loaded into memory, the current rate information is
displayed on the RATE page of the notebook. The user may select from a set of
standard sampling rates for common computer formats or may specify a specific
rate. OS/2 and Windows use standard rates which are multiples of 11025 Hz.
Sun, DEC, and NeXT computers commonly use a sampling rate of 8000 Hz.  Standard
rates of 8000, 11025, 22050, and 44100 Hz have been provided for the user to
select.

If the user wishes to use a sampling rate which is not one of these, the button
for Non-Standard should be pressed.  This will activate the slider bar and user
input windows to allow the user to specify the rate.  The slider bar can be
used to quickly change the rate in the input window or the user may select the
input window and type in the desired rate.


ΓòÉΓòÉΓòÉ 2.3.8. Speed ΓòÉΓòÉΓòÉ

This function will change the playback speed of a sample. This is the same
thing as setting a phonograph to a different speed such that the sound is
played too fast or too slow.  This function is similar to the RATE function
except that the target playback rate is changed as the sample is interpolated.
This function does use interpolation to predict the original analog waveform;
therefore, the resulting sample will contain slight errors just like the RATE
function.

The controls for this effect simply specify the new playback speed.  Once a new
speed is selected, the sample is resampled to interpolate the new playback
points. As a result, a sample is still played at the same rate, but the data is
modified to play at the new rate.  This allows the sample to be stored in a
file which is of a standard rate.

The user may select any of the standard rates including 8000 Hz, 11025 Hz,
22050 Hz, and 44100 Hz.  Additionally, the user may specify the playback speed
to be either double (x2) or half (x1/2) or may specify a specify playback speed
by selecting the User button.  If a speed other than the current speed is
specified, the DOIT button will be activated which will allow the user to
perform the change.


ΓòÉΓòÉΓòÉ 2.3.9. Echo ΓòÉΓòÉΓòÉ

An echo is created when sound reflects off an object (or multiple objects) and
returns to the originator at slight time offsets.  Each bounce reduces the
intensity of the sound such that the volume diminishes with each bounce.  The
ECHO tool is created by simulating a set of walls forward and aft of the source
such that the sound would bounce off of each wall and be reflected back to the
other wall.  In order for the ECHO effect to be strongly heard, at least two
echo points should be set up with total attenuation of less than 1.0.

The echo effect will modify a sample to provide attenuation at specific points
in a sample.  The operator must specify the points where the echo effects are
to start and an attenuation or Volume for the echo.  The attenuation determines
the length of time that it takes for the echo to die away.  If the Attenuation
specified for all of the echo points is greater than 1, then the echo will
"melt" rather than fading away and consequently may take a long time to
complete.  If an attenuation is set to 0 or less, the Echo point is ignored.

The echo effect presents an interesting challenge to the user interface.  How
do you provide the user with an intuitive method to set the echo locations and
the strength of the echo from a dialog box?  Well, look at the ECHO notebook
page and follow along in the explanation of the operation.  This notebook page
includes a graphical display of the current sample, a text entry field for
editing (e.g. adding or deleting) time marks, and a volume control for setting
the strength of the echo.

The ECHO notebook is centered around the graph at the top of the page.  This
display is the primary point of control. However, to allow for a bit more
direct control, the user may use the entry fields to add and delete echo points
too. To explain it all, I will start with the graphical display first and then
lead to the secondary controls.

Once a sample has been loaded into memory, the graphical display will become
active.  The display is controlled through two slider bars for the position in
the sample and for the magnification. The sample is normalized so that the
largest sample value will hit the limit of the display.  This makes the display
volume independent but gives maximum clarity of the actual waveform in memory.
Markers may be added or moved to set the echo points in the waveform.  To aid
the operator in locating the desired echo point, the display contains a status
bar for the starting timemark for the sample in the window, the current
timemark under the mouse, and the magnification factor.

To move to the right or left in the display, the horizontal slider bar may be
used.  Pressing the end arrows moves the display one displayed sample to the
left or right.  When the slider bar is pressed, the display will move one half
screen to the right or left.  The user may move the display to a region quickly
by selecting the slider button and dragging it to the appropriate position.
The display is immediately updated to display the current position.

The display area at the bottom of the graph provides a timemark indicator for
the first sample appearing at the left of the graph.  This provides a reference
for moving through the data.  The time marker is displayed in the form of
m:ss.ssss where m is the number of minutes into the sample and ss.ssss is the
number of seconds into the sample.

Even the smallest sample contains more data than can fit on the graphical
display.  For this reason the vertical slider to the right of the graphical
display is used to adjust the viewing magnification of the samples.  The
maximum magnification of the samples is determined by the length of the sample
and is calculated by dividing the total sample length by the largest number of
data points which may be scrolled through on the display.  The display is
limited to the maximum size of an signed 16 bit value due to the limitations of
the signals for the horizontal slider bar. This results in a maximum of 32767
data points which can be displayed and scrolled through.

Initially, the magnification is set for the maximum displayable.  To decrease
the magnification (i.e. zoom out) on the sample, move the slider down the bar.
The arrows on the ends of the bar can be used to increase or decrease the
magnification in increments of 1.  Selecting between the button and the arrows
doubles or halves the magnification. If the button is selected, the
magnification can be set immediately to a value.  Markers are displayed for the
nearest point in the zoom.  However, markers can only be set on exact multiples
of the zoom.  Therefore, when trying to move a marker, if it is set at a
different magnification, it may not be possible to move the marker without
returning to that zoom.  Essentially, the marker is displayed but cannot be
selected because that exact sample point is not visible. I considered making
the mouse select the nearest marker, but this is a point of confusion if many
markers are displayed at the same location for a specific magnification.

The current magnification is displayed in the status area of the display in the
form of "x1/nnnnn" where "nnnnn" is replaced by the current magnification
number (i.e. number of points represented by a single point on the display).
If the display says that the zoom is x1/2, then the magnification of the
display is halved.  If this sounds confusing, then just play with the notebook
page for a bit to get a feel for the operation of the zoom.

Before going on, another area of the display needs to be described.  The center
number on the status area of the display indicates the timemark for the current
(or last) mouse position. Whenever the mouse is moved into the display area,
this number will be updated to indicate the time offset for that particular
point.  This takes into account the magnification.

Now for the fun part.  To add an echo point to the sample, move the mouse to
the place where you desire the echo.  The status display will provide a
reference for the timemark. When the proper position has been selected, click
the mouse and a blue marker will be placed.  If the mouse is released, the
marker will be set at that location in the sample.  If the mouse is not
released, the marker may be dragged across the display. This marker may be
moved later if necessary by other means too.

Note:  If at any time the mouse pointer is moved outside of the display before
       the mouse button is released, the marker will not be set and the blue
       mark will be erased from the display.

  A echo marker may be moved by positioning the mouse pointer over the marker
 and pressing the mouse button.  If the marker is on a multiple of the zoom
 level, it will be selected and will follow the mouse as long as the button is
 pressed.  When the button is released, the marker will be placed at that
 position.

 A marker may be moved to another time delay by entering the desired delay
 directly through the Time Mark entry field.

 Note:  If the mouse is moved off the display area, the marker will be restored
        to its original position.

  For each marker displayed, the timemark is stored in a Combo Box.  This box
 is like an entry field in that the user can edit the time directly ; however,
 it also has a drop down box that can scroll vertically through all of the
 different markers.  This type of box provides a great deal of flexibility for
 the user.

 To add a marker at a specific time, position the cursor in the Timemark box
 and edit the time index.  The format is the same as that used to display the
 time marks in the main display.  Enter the number of minutes followed by the
 seconds.  The granularity of the seconds is on the order of 1/10000 of a
 second.  For example, entering 6:54.4253 would accept a time mark at 6
 minutes, 54.4253 seconds.  If a value is entered with is beyond the maximum
 sample of the file or less than 0, then the data is ignored.

 Once the desired time mark has been entered, the user may press the Add button
 to place the marker in the current database.  All timemarks added to the
 display use the volume specified for the last timemark, or 0 if no volume has
 been set yet.

 When the listbox is pulled down for the timemarks, each of the timemarks that
 have been entered are displayed in a vertically and horizontally scrollable
 window.  Up to 32 markers may be placed in the file and any markers which are
 unused are displayed with the word "EMPTY".  The markers are placed in the
 database in the order that they are entered unless a free slot is open (from
 being deleted).  The user may select any of the time marks using the combo
 box. If the selected timemark is not empty, the display will be updated to
 display the selected timemark in the center of the graph.  In the event that
 the timemark is too close to the end or beginning of the sample to display in
 the center of the graph, the timemark will be displayed without being
 centered.  Once a timemark has been selected, the Del button may be pressed to
 delete the marker from the database.  The entry field is not cleared in order
 to allow the user to directly edit the timemark which was deleted and add it
 later.

 The volume for each timemark may be set by specifying a value in the volume
 entry field.  This is a simple entry field in which the user can type or
 delete numbers.  Since the volume (attenuation) for each timemark may range
 from 0 to infinity, the only method for entering the volume is through the
 keyboard.  Sorry, no sliders here.  As each character is typed, it is stored.
 The user does not have to press enter or any key to accept the value.

 Note:  The most common mistake for the echo effect is in forgetting to enter a
        value in the Volume field.  Remember that you must provide an
        attenuation for the echo in the Volume entry field to make the echo
        point valid.


ΓòÉΓòÉΓòÉ 2.3.10. Invert ΓòÉΓòÉΓòÉ

Any series of samples may be inverted such that all positive values become
negative and all negative values become positive.  A sample is composed of
numbers which are digital snapshots of an analog wave at regular intervals.
These numbers can take on positive and negative values which push or release
the cone of a speaker to produce sound.

To the human ear, there is no difference in the sound produced; however,
mathematically, the new wave is very different.  An inverted wave may be added
to a normal wave to mathematically subtract one from another. When this
function is combined with the MERGE function of the editor, samples can be
added together to eliminate common frequencies.

The range and channels for this function are selected through the editor.


ΓòÉΓòÉΓòÉ 2.3.11. Reverse ΓòÉΓòÉΓòÉ

When the digital data of a sample is reversed, the effect is that of playing a
record backwards.

This effect allows the user to reverse a section (or all) of a sample.  The
range and channels for this function are selected through the editor.


ΓòÉΓòÉΓòÉ 2.3.12. Vibro ΓòÉΓòÉΓòÉ

This tool simulates the effect of driving a sound through a rotating fan such
that the intensity of the sample is modified at a regular interval.

This function performs the "world-famous" Fender Vibro-Champ sound effect to a
sound sample by using a sine wave as the amplitude of the volume at each
sample.  This tool requires that the user set the Speed and the Depth of the
sine wave.

The speed setting gives the frequency of the sine wave in Hertz.  The range of
values for the slider are from 1 to 30 in increments of 1 Hertz.  A value of 0
would be useless for a frequency and is not allowed.

The depth setting gives the amount by which the volume will be cut into by the
sine wave.  The range of values for the slider are from 0.0 to 1.0 in
increments of 0.01.  The initial value of the slider is 0.5.


ΓòÉΓòÉΓòÉ 2.3.13. Fade ΓòÉΓòÉΓòÉ

This effect allows the user to either fade in or fade out the volume of a
sample.  Fading the data in a sample is produced by increasing or decreasing
the volume of the sample over a period.  To fade a sample in is to slowly
increase the volume of the sample from 0 to the normal volume of the sample
over a block of time.  To fade the sound out is just the opposite in which the
volume of the sample is slowly reduced over a period.

The FADE tool provides three methods for fading which provide a robust means
for controlling the volume of the data over the specified range of operation.
These are Linear, Slow Geometric, and Fast Geometric.


ΓòÉΓòÉΓòÉ 2.3.14. Limit ΓòÉΓòÉΓòÉ

Most anyone who has received a sound sample from different sources has had the
problem that the recorded volume is inconsistent between different samples.
After all, there is no standard recording level for the different machines or
different software.

To allow the user to adjust the volume of a sample, PMsndX provides a tool
which can either adjust the volume by multiplying every sample by a fixed
amount or by multiplying the samples by a value based on the limit of the data
that can held in memory.

By specifying a maximum value for the sound sample, all sound samples can be
set to have a similar maximum.  The obvious use for this function is to allow a
library of sounds to be set at the same volume.  The value used for the maximum
volume is based on a percentage of the maximum data that can be held in a
single sample.  As an example, a value of 100% for the volume represents a
value of 127 for a signed byte sample.

When the button for the Maximum is selected, the slider bar directly beneath
the button is activated.  Initially, this will be set to the current volume in
terms of the percentage of the maximum value for the sample.  The volume may be
adjusted by setting the slider to a value between 0 and 100 percent of the
maximum.

Since the value is based on a percentage of the maximum value of the data that
can be stored in a sample, clipping is not possible.

When the button for the Fixed value is selected, the slider bar directly
beneath the button is activated as well as the checkbox for clipping.  The
fixed bar provides the means to multiply all sound samples by a fixed value
between 0 and 2 in increments of 0.1. A value of 1 makes no change.  Any value
greater than 1 increases the volume and any value less than 1 decreases the
volume.  A value of 2 doubles the volume of the sample.

When using fixed sampling it is possible to exceed the maximum data that may be
stored for a sample.  The Allow Clipping checkbox may be selected to allow the
data to be clipped.  If the checkbox is not set and if the fixed multiple will
result in clipping, then the multiple will be set to the maximum value that
will not result in clipping.  If the clipping box is set, data may exceed the
maximum that may be stored for the sample which will result in noise.


ΓòÉΓòÉΓòÉ 2.3.15. Balance ΓòÉΓòÉΓòÉ

When a sample has more than one channel, the volume of the individual channels
can be varied.  The balance of the channels can be achieved either
instantaneously or over a period of time.  These are the same basic functions
as used in the FADE and SWAP effects and are Linear, Slow Geometric, and Fast
Geometric, and Step.

The volume of a sample may vary by either starting at the specified percentage
of the current volume for each channel and progressively approaching full
volume.  This is similar to fading in a sample and is achieved by selecting the
"IN" button.  The opposite effect is achieved when the volume starts at the
current volume and progressively decreases to a percentage of the current
volume.

When balancing a sample, the user must specify a percentage for each channel.
When fading in, this is the percentage that the volume will start at for each
respective channel. When fading out, this is the final percentage of the
original volume.  The display at the top of this dialog varies depending on the
number of channels in the current sample.


ΓòÉΓòÉΓòÉ 2.4. Rexx ΓòÉΓòÉΓòÉ

EdSndX integrates the features of REXX to provide a powerful command scripting
capability.  EdSndX provides the necessary extensions to REXX to provide full
access to all of the features normally provided through the dialogs of the user
interface.  Unlike sound samples, only one REXX script can be open at a time.
The REXX script runs as a subfunction of the control panel and provides a
syntax which can manipulate each sample that is open through a handle which is
returned to the REXX script with the sample is opened or created.

Any REXX command script can be run through any of the means for opening a file
such as using the OPEN dialog box or through a DRAG/DROP operation.  As with
all REXX command scripts, the first line of the file must be a comment of the
form /* ... */. PMsndX will automatically recognize a command script using the
extension of .CMD or the OPEN dialog allows any file to be recognized as a
command script by providing an override in the Format group of the OPEN dialog.

As with any REXX script, the SAY command may be used to write to standard
output (stdout); and, the PULL command may be used to retrieve information from
standard input (stdin). When input is requested from the REXX window, the
desktop focus will automatically be directed to the REXX window and it will be
brought to the foreground.

Note:  Do not use CHARIN to retrieve input from the keyboard.

 The syntax of the language is divided up into groups associated with the
 buttons on the main control panel. Additionally, a few other controls are
 provided to enhance a script capability for enhancing the user interface.

 When a REXX command script is run, a REXX OUTPUT window (see illustration
 below)  is opened to display any outputs from the script.  By default, all
 standard outputs (e.g. output from SAY commands or commands echoed) are
 displayed in black.  Outputs from PMsndX commands is written in blue, and any
 errors are written in red.  A REXX script can be stopped at any time by
 closing the REXX OUTPUT window.  If no errors occur while executing the REXX
 command script, the REXX OUTPUT window will automatically be dismissed.  If
 errors occur, the window will remain open until the user closes it.  Only one
 REXX OUTPUT window can be open at any one time so the window must be closed
 before another REXX script can be run.  The colors used to display the REXX
 output may be modified through the properties dialog.

 Note:  As with REXX scripts, all commands can be entered in any combination of
        lower and upper case.  For example, the following commands are
        equivalent: "file open tmp.au", "FILE open TMP.AU", "FiLe OpEn TmP.Au".


ΓòÉΓòÉΓòÉ 2.4.1. Syntax Conventions ΓòÉΓòÉΓòÉ

The extensions provided by EdSndX have been designed to utilize a consistent
format.  The extensions are divided into three groups:  commands, functions,
and arguments.

REXX functions are those extensions provided by PMsndX which require that
PMsndX return some value to the calling REXX script.  The function extensions
use the arguments to specify the information that is to be returned.

REXX arguments are the keywords and parameters which are added to commands and
functions to provide information about the specific task to be performed.  All
arguments follow a repetitive format which utilizes keywords which usually have
associated parameters.


ΓòÉΓòÉΓòÉ 2.4.1.1. Function Syntax ΓòÉΓòÉΓòÉ

REXX functions are composed of a name followed by keyword and parameter
combinations separated by commas and enclosed in parenthesis.  Functions are
used to return data to the calling REXX script and so always appear on the
right side of an = character.

The general syntax of a function is:

X=FUNCTION(keyword, Parameter, [,keyword, Parameter,...])


ΓòÉΓòÉΓòÉ 2.4.1.2. Argument Syntax ΓòÉΓòÉΓòÉ

The Arguments used in EdSndX should be in order of a keyword followed
immediately by a parameter (if one is necessary). All required
keyword/parameter combinations must appear first, followed by any optional
keyword/parameter combinations.

To convey the syntax of the REXX extensions, the individual components are
color keyed to indicate their use. The following legend should be referred to
when reading the actual command and function syntax:

FUNCTION: The name of the function is always first and is required.

keyword:  Special keywords are used to indicate that a parameter is being
specified for a command. The keywords of a command may be entered in any order
but must be followed by their corresponding parameter.

Parameters:  Portions of a command which are used as variable parameters can
take on different formats and must be entered after the corresponding keyword.

[...]:  Parameters which are optional will appear between brackets ([]).
Anything between the brackets is not required for the command but may be added
to modify the operation.

When numeric values are required, the format will be indicated as follows:

'mm:ss.hhhh' indicates that a time is to be entered. The format indicates that
the time is to be given in minutes followed by a colon (:), the number of
seconds followed by a period (.) and the fractions of seconds.  For example,
'10:58.0001' indicates 10 minutes, 58 seconds, and 1 ten-thousandth of a
second.  Note that the time must be enclosed between single quotes.

#.# indicates that a decimal number is to be entered.  The range for the number
is provided in braces immediately following.  For example, #.#{0.0-1.0}
indicates that a number between 0.0 and 1.0 inclusive is requred.

#{range} indicates that a numeric value is required and the range is specified
in the braces.  For example, #{1-8192} indicates that a numeric value between 1
and 8192 inclusive is required.

'text' indicates that a text string is required.  The text must be enclosed in
single quotes and must appear as the last parameter in the line.  All data
after the keyword TEXT will be treated as the text for the operation.

{item1,item2,...} is used to indicate that a finite set of values are required.

Note:  The parameter YES is equivalent to setting a checkbox.  The parameter NO
       is equivalent to clearing a checkbox.

 Descriptions:  With each command group is a short description of the operation
 of the commands in that group. Additionally, every command may also have
 special information which is unique to the command or pertinent to the usage
 of the command.


ΓòÉΓòÉΓòÉ 2.4.2. File Operations ΓòÉΓòÉΓòÉ

All of the features of the OPEN and SAVE dialog boxes are available through the
FILE operations.  In addition to the standard items in the dialog box, the
capability to set the default OPEN and SAVE paths is provided to simplify batch
operations.

The FILE operations are provided through functions and return a handle which is
used to reference the file.  There are two reasons that the FILE commands are
implemented as functions instead of subcommands.  The parameters of a
subcommand are separated by spaces or other special parameters which EdSndX
does not receive even if the parameters are in quotations.  By using the
function interface to REXX, PMsndX receives the necessary delimiters to allow
filenames to contain special characters and spaces.

x=FILE(OPENPATH, PATH)

Filenames can be specified in any form (i.e. they may contain a drive letter, a
file path, and the actual filename).  However, to make batch operations
simpler, the path and drive may be specified using this command and any
filenames without paths or drives will use the OPENPATH to locate the file.  By
default, the current working directory will be used as the OPENPATH.

x=FILE(SAVEPATH, PATH)

When saving a file, a default path can be saved similar to the OPENPATH
command.  All save operations in which the drive and path are not specified
will use the specified path.  By default, the current working directory will be
used as the SAVEPATH.

handle=FILE(OPEN, filename, [FORMAT, {AU, AIF, AVI, HCM, SF, VOC, SMP, WAV,
IFF}])

handle=FILE(OPEN, filename, [FORMAT, {UB, SB, UL}, RATE, #{1-65535}, CHANNELS,
{1,2,4}])

handle=FILE(OPEN, filename, [FORMAT, {UW, SW}, RATE, #{1-65535}, CHANNELS,
{1,2,4}, ENDIAN, {BIG, LITTLE}])

Filenames must contain the name of a valid file and may optionally include a
drive letter and a specific path. If the path and drive letter are not
specified, PMsndX will use the current working directory or the path specified
in the OPENPATH command.

x=FILE(HANDLE, handle SAVE, [FORMAT, {AU, AIF, HCM, SF, VOC, SMP, WAV, IFF, UB,
SB, UL}])

x=FILE(HANDLE, handle, SAVEAS, filename, [FORMAT, {AU, AIF, HCM, SF, VOC, SMP,
WAV, IFF, UB, SB, UL}])

x=FILE(HANDLE, handle, SAVE, [FORMAT, {UW, SW}, ENDIAN, {BIG, LITTLE}])

x=FILE(HANDLE, handle, SAVEAS, filename, [FORMAT, {UW, SW}, ENDIAN, {BIG,
LITTLE}])

When the SAVE form is used, the current filename for the sample is used.  When
the SAVEAS form is used, a valid filename must be provided.  Filenames must
contain the name of a valid file and may optionally include a drive letter and
a specific path. If the path and drive letter are not specified, PMsndX will
use the current working directory or the path specified in the SAVEPATH
command.

x=FILE(HANDLE, handle, CLOSE)

This closes the editor display for the file handle specified without saving.


ΓòÉΓòÉΓòÉ 2.4.3. Audio Operations ΓòÉΓòÉΓòÉ

All operations available through the AUDIO section of the editor are accessible
through the AUDIO Operations group.  The value returned for all AUDIO
operations indicates the success of the operation.

x=AUDIO(VOLUME, #{0-100})

The volume control is global across all editors and so there is no association
of the VOLUME in the REXX script with a particular editor window.

x=AUDIO(HANDLE, handle, PLAY, {ASYNC, SYNC})

The ASYNC option causes the sound to start playing and lets the REXX script
continue.  The SYNC option causes the REXX script to pause while waiting for
the playback to complete.

x=AUDIO(HANDLE, handle, REWIND)

handle=AUDIO(RECORD, {ASYNC, SYNC}, TIME, 'mm:ss.hhhh', INPUT, {MIC, LINE},
QUALITY, {8, 16}, CHANNELS, {1, 2}, RATE, #{1-65535}, [OVERWRITE, {YES, NO}],
[MONITOR, {YES, NO}])

handle=AUDIO(RECORD, {ASYNC, SYNC}, COUNT, #{1-}, INPUT, {MIC, LINE}, QUALITY,
{8, 16}, CHANNELS, {1, 2}, RATE, #{1-65535}, [OVERWRITE, {YES, NO}], [MONITOR,
{YES, NO}])

handle=AUDIO(RECORD, {ASYNC, SYNC}, MEMORY, #{1-}, INPUT, {MIC, LINE}, QUALITY,
{8, 16}, CHANNELS, {1, 2}, RATE, #{1-65535}, [OVERWRITE, {YES, NO}], [MONITOR,
{YES, NO}])

When the AUDIO RECORD function is used, a new editor window is automatically
created without a filename.  The return value for the record functions is the
handle for the window which is of the same form as the handle returned from a
FILE OPEN operation.  The SAVEAS form of the FILE function must be used when
saving the new samples.


ΓòÉΓòÉΓòÉ 2.4.4. Properties Operations ΓòÉΓòÉΓòÉ

All PROPERTIES functions return the current value of the property prior to
changing it.

x=PROPERTIES(ENABLE_MMPM, {YES, NO})

x=PROPERTIES(SHARE_AUDIO, {YES, NO})

x=PROPERTIES(PLAY_16ON8, {YES, NO})

x=PROPERTIES(DEVICE, devicename)

x=PROPERTIES(MEMORY, AUTO)

x=PROPERTIES(MEMORY, #{1-8192})

x=PROPERTIES(IGNORE_HEADER_STYLE, {YES, NO})

x=PROPERTIES(REQUIRE_AU_HEADER, {YES, NO})

x=PROPERTIES(FORCE_ULAW, {YES, NO, MAYBE})

x=PROPERTIES(INI_PATH, path)

x=PROPERTIES(REXX_STDIN_COLOR, {BLACK, BLUE, RED, PINK, GREEN, CYAN, YELLOW,
GREY, DGREY, DBLUE, DRED, DPINK, DGREEN, DCYAN, DYELLOW, LGREY})

x=PROPERTIES(REXX_STDOUT_COLOR, {BLACK, BLUE, RED, PINK, GREEN, CYAN, YELLOW,
GREY, DGREY, DBLUE, DRED, DPINK, DGREEN, DCYAN, DYELLOW, LGREY})

x=PROPERTIES(REXX_STDERR_COLOR, {BLACK, BLUE, RED, PINK, GREEN, CYAN, YELLOW,
GREY, DGREY, DBLUE, DRED, DPINK, DGREEN, DCYAN, DYELLOW, LGREY})

x=PROPERTIES(REXX_COMMAND_COLOR, {BLACK, BLUE, RED, PINK, GREEN, CYAN, YELLOW,
GREY, DGREY, DBLUE, DRED, DPINK, DGREEN, DCYAN, DYELLOW, LGREY})

x=PROPERTIES(REXX_DISPLAY_HISTORY, #{64-32767})

x=PROPERTIES(FOOTNOTES, {YES, NO})

x=PROPERTIES(SAVE_POSITIONS, {YES, NO})

x=PROPERTIES(SAVE_OPENPATH, {YES, NO})

x=PROPERTIES(SAVE_SAVEPATH, {YES, NO})

x=PROPERTIES(PLAY_ON_COMMANDLINE_LOAD, {YES, NO})

x=PROPERTIES(EXIT_AFTER_COMMANDLINE_PLAY, {YES, NO})

x=PROPERTIES(FREE_MEMORY_AFTER_LOADING, {YES, NO})

x=PROPERTIES(ENABLE_QUICK_QUEUEING, {YES, NO})

x=PROPERTIES(AUTO_RATE_ADJUST, {YES, NO})

x=PROPERTIES(UNDO, {YES, NO})

x=PROPERTIES(USE_DISPLAYED_CHANNEL, {YES, NO})

x=PROPERTIES(USE_DISPLAYED_RANGE, {YES, NO})

X=PROPERTIES(EDITOR_INFO, {YES, NO})

X=PROPERTIES(EDITOR_ALL_CHANNELS, {YES, NO})

X=PROPERTIES(EDITOR_DELAY_AUDIO_LOADING, {YES, NO})

X=PROPERTIES(EDITOR_SETUP_AUDIO_AT_PLAY, {YES, NO})

X=PROPERTIES(EDITOR_AUTO_REPEAT, {YES, NO})

X=PROPERTIES(EDITOR_FORMAT_TIME, {YES, NO})

X=PROPERTIES(EDITOR_PLAY_MODE_RANGE, {YES, NO})


ΓòÉΓòÉΓòÉ 2.4.5. Edit Operations ΓòÉΓòÉΓòÉ

The value returned for all EDIT operations indicate the success of the
operation.

X=EDIT(HANDLE, handle, MANIPULATE, {ALL, 1, 2, 3, 4})

x=EDIT(HANDLE, handle, AREA, ENTIRE_SAMPLE)

x=EDIT(HANDLE, handle, AREA, PART, START, 'mm:ss.hhhh', END, 'mm:ss.hhhh')

x=EDIT(HANDLE, handle, {COPY, CUT, PASTE, ZERO, REMOVE, CLEAR, MERGE, UNDO})

x=EDIT(HANDLE, handle, {PASTEFROM, MERGEFROM}, handle)


ΓòÉΓòÉΓòÉ 2.4.6. Effects Operations ΓòÉΓòÉΓòÉ

The value returned for all EDIT operations indicate the success of the
operation.

x=TOOLS(HANDLE, handle, FORMAT, {AU, AIF, HCM, SF, VOC, SMP, WAV, IFF, UB, SB,
UL, UW, SW})

x=TOOLS(HANDLE, handle, AVERAGE, 2_TO_1, FROM, {LEFT, CENTER, RIGHT})

x=TOOLS(HANDLE, handle, AVERAGE, 4_TO_1, FROM, {FL, FR, RL, RR}, [FROM, {FL,
FR, RL, RR}...])

x=TOOLS(HANDLE, handle, AVERAGE, 4_TO_2, FROM, {FL, FR, RL, RR}, TO, {L, R},
[FROM, {FL, FR, RL, RR}, TO, {L, R}...])

x=TOOLS(HANDLE, handle, DUPE, {1_TO_2, 1_TO_4})

x=TOOLS(HANDLE, handle, DUPE, 2_TO_4, FROM, {L, R}, TO, {FL, FR, RL, RR},
[FROM, {L, R}, TO, {FL, FR, RL, RR}...])

x=TOOLS(HANDLE, handle, RATE, #{1-65535})

x=TOOLS(HANDLE, handle, SPEED, #{1-65535})

x=TOOLS(HANDLE, handle, SPEED, {X2, X1/2})


ΓòÉΓòÉΓòÉ 2.4.6.1. Filter Effects Operations ΓòÉΓòÉΓòÉ

x=TOOLS(HANDLE, handle, FILTER, BANDPASS, START, #{1-65535}, CUTOFF,
#{1-65535}, [ADD_NOISE, {YES, NO}])

x=TOOLS(HANDLE, handle, FILTER, BANDPASS, CENTER, #{1-65535}, WIDTH,
#{1-65535}, [ADD_NOISE, {YES, NO}])

x=TOOLS(HANDLE, handle, FILTER, LOWPASS, CENTER, #{1-65535}, GAIN,
#.#{0.0-1.0})


ΓòÉΓòÉΓòÉ 2.4.6.2. Special Effects Operations ΓòÉΓòÉΓòÉ

x=TOOLS(HANDLE, handle, EFFECT, ECHO, MARK, 'mm:ss.hhhh', VOLUME, #.#{0.0-1.0},
[MARK, 'mm:ss.hhhh', VOLUME, #.#{0.0-1.0}, ...])

x=TOOLS(HANDLE, handle, EFFECT, INVERT)

x=TOOLS(HANDLE, handle, EFFECT, REVERSE)

x=TOOLS(HANDLE, handle, EFFECT, VIBRO, SPEED, #{0-30}, DEPTH, #.#{0.0-1.0})

x=TOOLS(HANDLE, handle, EFFECT, FADE, DIRECTION, {IN, OUT}, METHOD, {LINEAR,
SLOW, FAST})

x=TOOLS(HANDLE, handle, EFFECT, LIMIT, MAX, #{0-100})

x=TOOLS(HANDLE, handle, EFFECT, LIMIT, MULTIPLE, #.#{0.0-2.0})

x=TOOLS(HANDLE, handle, EFFECT, BALANCE2, L, #{0-100}, R, #{0-100}, DIRECTION,
{IN, OUT}, METHOD, {LINEAR, SLOW, FAST, STEP})

x=TOOLS(HANDLE, handle, EFFECT, BALANCE4, FL, #{0-100}, FR, #{0-100}, RL,
#{0-100}, RR, #{0-100}, DIRECTION, {IN, OUT}, METHOD, {LINEAR, SLOW, FAST,
STEP})


ΓòÉΓòÉΓòÉ 2.4.7. User Operations ΓòÉΓòÉΓòÉ

EdSndX also provides a dialog method of user input through standard OS/2
MESSAGE dialog boxes.  A message dialog provides the user with a means to
present text with a dialog containing a icon and standard buttons along with
standard OS/2 system sounds to catch the attention of the user.  Since a value
is returned from the MESSAGE, it must be formatted as a function.

x=MESSAGE(HANDLE, handle, ASK, {OK, OKCANCEL, CANCEL, ENTER, ENTERCANCEL,
RETRYCANCEL, ABORTRETRYIGNORE, YESNO, YESNOCANCEL}, ICON, {NOICON, ICONHAND,
QUESTION, EXCLAMATION, ASTERISK, INFORMATION, QUERY, WARNING, ERROR}, [MODE,
{APPLICATION, SYSTEM},] [MOVEABLE, {YES, NO},] TEXT, 'text', TITLE, 'text')

The ASK parameter determines the possible return values. The data returned is a
string representing the button pressed by the user.  The possible return values
are:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéType            ΓöéReturn  Γöé
Γöé                Γöé        Γöé
ΓöéOK              ΓöéOK      Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
Γöé                Γöé        Γöé
ΓöéOKCANCEL        ΓöéOK      Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéCANCEL  Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
Γöé                Γöé        Γöé
ΓöéCANCEL          ΓöéCANCEL  Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
Γöé                Γöé        Γöé
ΓöéENTER           ΓöéENTER   Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
Γöé                Γöé        Γöé
ΓöéENTERCANCEL     ΓöéENTER   Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéCANCEL  Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
Γöé                Γöé        Γöé
ΓöéRETRYCANCEL     ΓöéRETRY   Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéCANCEL  Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
Γöé                Γöé        Γöé
ΓöéABORTRETRYIGNOREΓöéABORT   Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéRETRY   Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéIGNORE  Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
Γöé                Γöé        Γöé
ΓöéYESNO           ΓöéYES     Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéNO      Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
Γöé                Γöé        Γöé
ΓöéYESNOCANCEL     ΓöéYES     Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéNO      Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéCANCEL  Γöé
Γöé                Γöé        Γöé
Γöé                ΓöéERROR   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following ICONs and the associated sounds for the dialog (from the System
Events in the MMPM Sound setup):

      NOICON - () - NONE
      ICONHAND - () - Error sound
      QUESTION - () - Information sound
      EXCLAMATION - () - Warning sound
      ASTERISK - () - NONE
      INFORMATION - () - NONE
      QUERY - () - Information sound
      WARNING - () - Warning sound
      ERROR - () - Error sound

 The MODE specifies how the window is displayed with relation to other windows
 on the system.  If no MODE keyword is specified or APPLICATION is specified,
 then the dialog window will can be covered by other windows from the desktop.
 If SYSTEM is specified, then the dialog box will prevent other windows on the
 desktop from covering it.

 The MOVEABLE keyword is used to determine if a titlebar is provided on the
 message dialog box.  If the MOVEABLE keyword is not specified or if it is
 specified as NO, then there will be no titlebar on the message dialog and it
 cannot be moved around the screen.  Specifying YES allows the user to move the
 message dialog box around the screen.


ΓòÉΓòÉΓòÉ 2.4.8. Miscellaneous Operations ΓòÉΓòÉΓòÉ

The value returned for all EDIT operations indicate the success of the
operation.

x=PMSNDX(EXIT)

The EXIT keyword sends a message to PMsndX to exit.  This is the same as
clicking CLOSE on the system menu of the control panel.

x=PMSNDX(UPDATEWINDOWS)

The UPDATEWINDOWS keyword forces PMsndX to update all windows that are
currently displayed.  During the processing of a REXX script, most windows are
not updated when they are open.  Of course there are exceptions to this such as
the EDITOR and the AUDIO dialogs in which updates are required to allow the
user to maintain control over the current operation.

x=PMSNDX(CLOSE, {YES,NO})

If no errors occur during the execution of a REXX script, the REXX output
window will automatically close itself.  However, by specifying the CLOSE
keyword and the parameter YES, the window can be forced to remain open.  In the
event that an error occurs in the REXX script, this command has no effect.

x=PMSNDX(IGNORE_SYNTAX_ERRORS, {YES,NO})

When writing REXX scripts for PMsndX, it may be desirable to pass the REXX
through the interpreter to check the syntax of the commands without having
PMsndX stop at each error.  When this option is turned on, PMsndX will still
display the errors in RED, but will not stop after the error.

x=PMSNDX(OUTPUT, {YES,NO})

By default, PMsndX displays each PMsndX command or function as it is executed.
This output can be turned off with this command by specifying NO

x=PMSNDX(TEST_MODE, {YES,NO})

By setting PMsndX into REXX TEST_MODE, REXX scripts will be processed as usual
except that the commands will not actually be executed.  This option is
primarily used during the testing of the REXX syntax parser during the
development of PMsndX, and has been provided to allow scripts to be tested
syntatically before using them.

return 'text'


ΓòÉΓòÉΓòÉ 2.4.9. Query/Test Operations ΓòÉΓòÉΓòÉ

The functions which make up the QUERY group return values which are identical
to the parameters expected by the indicated command.  To determine the range of
values that may be returned, see the corresponding command and keyword
combinations.

X=QUERY(FILE, OPENPATH)

X=QUERY(FILE, SAVEPATH)

X=QUERY(HANDLE, handle, FILE, FILENAME)

X=QUERY(HANDLE, handle, INFO, FORMAT)

X=QUERY(HANDLE, handle, INFO, DATASTYLE)

X=QUERY(HANDLE, handle, INFO, CHANNELS)

X=QUERY(HANDLE, handle, INFO, RATE)

X=QUERY(HANDLE, handle, INFO, DATASIZE)

X=QUERY(HANDLE, handle, INFO, SAMPLES)

X=QUERY(HANDLE, handle, INFO, TIME)

X=QUERY(HANDLE, handle, INFO, MEMORY)

X=QUERY(HANDLE, handle, INFO, COMMENT)

X=QUERY(HANDLE, handle, INFO, BYTEORDER)

X=QUERY(HANDLE, handle, AUDIO, VOLUME)

X=QUERY(HANDLE, handle, AUDIO, TIME)

X=QUERY(HANDLE, handle, AUDIO, COUNT)

X=QUERY(HANDLE, handle, AUDIO, MEMORY)

X=QUERY(HANDLE, handle, AUDIO, INPUT)

X=QUERY(HANDLE, handle, AUDIO, QUALITY)

X=QUERY(HANDLE, handle, AUDIO, CHANNELS)

X=QUERY(HANDLE, handle, AUDIO, RATE)

X=QUERY(HANDLE, handle, AUDIO, OVERWRITE)

X=QUERY(HANDLE, handle, AUDIO, MONITOR)

X=QUERY(PROPERTIES, ENABLE_MMPM)

X=QUERY(PROPERTIES, SHARE_AUDIO)

X=QUERY(PROPERTIES, PLAY_16ON8)

X=QUERY(PROPERTIES, DEVICE)

X=QUERY(PROPERTIES, MEMORY)

X=QUERY(PROPERTIES, IGNORE_HEADER_STYLE)

X=QUERY(PROPERTIES, REQUIRE_AU_HEADER)

X=QUERY(PROPERTIES, FORCE_ULAW)

X=QUERY(PROPERTIES, INI_PATH)

X=QUERY(PROPERTIES, REXX_STDIN_COLOR)

X=QUERY(PROPERTIES, REXX_STDOUT_COLOR)

X=QUERY(PROPERTIES, REXX_STDERR_COLOR)

X=QUERY(PROPERTIES, REXX_COMMAND_COLOR)

X=QUERY(PROPERTIES, REXX_DISPLAY_HISTORY)

X=QUERY(PROPERTIES, FOOTNOTES)

X=QUERY(PROPERTIES, SAVE_POSITIONS)

X=QUERY(PROPERTIES, SAVE_OPENPATH)

X=QUERY(PROPERTIES, SAVE_SAVEPATH)

X=QUERY(PROPERTIES, PLAY_ON_COMMANDLINE_LOAD)

X=QUERY(PROPERTIES, EXIT_AFTER_COMMANDLINE_PLAY)

X=QUERY(PROPERTIES, FREE_MEMORY_AFTER_LOADING)

X=QUERY(PROPERTIES, ENABLE_QUICK_QUEUEING)

X=QUERY(PROPERTIES, AUTO_RATE_ADJUST)

X=QUERY(PROPERTIES, UNDO)

X=QUERY(PROPERTIES, USE_DISPLAYED_CHANNEL)

X=QUERY(PROPERTIES, USE_DISPLAYED_RANGE)

X=QUERY(PROPERTIES, EDITOR_INFO)

X=QUERY(PROPERTIES, EDITOR_ALL_CHANNELS)

X=QUERY(PROPERTIES, EDITOR_DELAY_AUDIO_LOADING)

X=QUERY(PROPERTIES, EDITOR_SETUP_AUDIO_AT_PLAY)

X=QUERY(PROPERTIES, EDITOR_AUTO_REPEAT)

X=QUERY(PROPERTIES, EDITOR_FORMAT_TIME)

X=QUERY(PROPERTIES, EDITOR_PLAY_MODE_RANGE)

x=QUERY(PMSNDX, VERSION)

Returns the current version number.

x=QUERY(PMSNDX, REGISTERED)

Returns {YES,NO} to indicate whether PMsndX has been registered.

x=QUERY(PMSNDX, ERROR_OCCURRED)

Returns {YES,NO} indicating whether an error has occurred.  If this is set to
YES then the REXX output window will not close when the REXX script has
completed execution.

x=QUERY(PMSNDX, CLOSE)

Returns {YES,NO} indicating whether the REXX script has told PMsndX not to
close the REXX output window when the script completes.

x=QUERY(PMSNDX, IGNORE_SYNTAX_ERRORS)

Returns {YES,NO} indicating whether the PMsndX has been told to ignore errors.

x=QUERY(PMSNDX, OUTPUT)

Returns {YES,NO} indicating whether the PMsndX commands are echoed in the REXX
output window.

x=QUERY(PMSNDX, TEST_MODE)

Returns {YES,NO} indicating that the PMsndX is in TEST_MODE.


ΓòÉΓòÉΓòÉ 2.4.10. Animation Operations ΓòÉΓòÉΓòÉ

The value returned for all EDIT operations indicate the success of the
operation.

During the processing of a REXX script, the various dialogs may be
automatically opened and the user may wish to "clean up" the screen before
completing the rexx script.  A set of controls is provided to allow for user
controlled animation of the desktop.

x=DISPLAY(ABOUT, {YES, NO})

x=DISPLAY(WELCOME, {YES, NO})

x=DISPLAY(TOOLS, {YES, NO})

x=DISPLAY(TOOLPAGE, {INFO, FORMAT, CHANNELS, AVERAGE, DUPE, FILTER, BANDPASS,
LOWPASS, SAMPLE, RATE, SPEED, EFFECT, ECHO, INVERT, REVERSE, VIBRO, VOLUME,
FADE, LIMIT, BALANCE})

x=DISPLAY(OPEN, {YES, NO})

x=DISPLAY(PROPERTIES, {YES, NO})

x=DISPLAY(PROPPAGE, {AUDIO, MEMORY, MISC, REXX, STARTUP, PLSNDX, EDSNDX,
EDITOR})


ΓòÉΓòÉΓòÉ 2.4.11. REXX return values ΓòÉΓòÉΓòÉ

Both FUNCTIONS and COMMANDS return error codes in the event that an error
occurs when processing the commands.  The error codes are composed of two 8 bit
numbers logically ORed together.

The upper 8 bits of the return code indicates the command command group which
caused the error.  The following table lists the possible values.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéGroup               ΓöéValue       Γöé
Γöé                    Γöé            Γöé
ΓöéNo Error            Γöé0           Γöé
Γöé                    Γöé            Γöé
ΓöéUnknown             Γöé0x00000100  Γöé
Γöé                    Γöé            Γöé
ΓöéFILE                Γöé0x00000200  Γöé
Γöé                    Γöé            Γöé
ΓöéAUDIO               Γöé0x00000300  Γöé
Γöé                    Γöé            Γöé
ΓöéPROPERTIES          Γöé0x00000400  Γöé
Γöé                    Γöé            Γöé
ΓöéEDIT                Γöé0x00000500  Γöé
Γöé                    Γöé            Γöé
ΓöéTOOLS               Γöé0x00000600  Γöé
Γöé                    Γöé            Γöé
ΓöéMESSAGE             Γöé0x00000700  Γöé
Γöé                    Γöé            Γöé
ΓöéPMSNDX              Γöé0x00000800  Γöé
Γöé                    Γöé            Γöé
ΓöéQUERY               Γöé0x00000900  Γöé
Γöé                    Γöé            Γöé
ΓöéDISPLAY             Γöé0x00000a00  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The lower 8 bits of the result indicate the reason for the error. The possible
values are listed in the following table.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéError               ΓöéValue       Γöé
Γöé                    Γöé            Γöé
ΓöéNo Error            Γöé0           Γöé
Γöé                    Γöé            Γöé
ΓöéNOT IMPLEMENTED     Γöé0x00000001  Γöé
Γöé                    Γöé            Γöé
ΓöéBAD VALUE           Γöé0x00000002  Γöé
Γöé                    Γöé            Γöé
ΓöéUNKNOWN PARAMETER   Γöé0x00000003  Γöé
Γöé                    Γöé            Γöé
ΓöéUNKNOWN KEYWORD     Γöé0x00000004  Γöé
Γöé                    Γöé            Γöé
ΓöéUNKNOWN COMMAND     Γöé0x00000005  Γöé
Γöé                    Γöé            Γöé
ΓöéUNKNOWN FUNCTION    Γöé0x00000006  Γöé
Γöé                    Γöé            Γöé
ΓöéMISSING HANDLE      Γöé0x0000000e  Γöé
Γöé                    Γöé            Γöé
ΓöéINVALID HANDLE      Γöé0x0000000f  Γöé
Γöé                    Γöé            Γöé
ΓöéMISSING PARAMETER   Γöé0x00000007  Γöé
Γöé                    Γöé            Γöé
ΓöéMISSING KEYWORD     Γöé0x00000008  Γöé
Γöé                    Γöé            Γöé
ΓöéMISSING COMMAND     Γöé0X00000009  Γöé
Γöé                    Γöé            Γöé
ΓöéMISSING FUNCTION    Γöé0X0000000a  Γöé
Γöé                    Γöé            Γöé
ΓöéUNBALANCED KEYWORD  Γöé0x0000000b  Γöé
Γöé                    Γöé            Γöé
ΓöéEXTRA DATA          Γöé0x0000000c  Γöé
Γöé                    Γöé            Γöé
ΓöéDUPLICATE KEYWORD   Γöé0x0000000d  Γöé
Γöé                    Γöé            Γöé
ΓöéINVALID PATH        Γöé0x00000010  Γöé
Γöé                    Γöé            Γöé
ΓöéBAD FILE NAME       Γöé0x00000011  Γöé
Γöé                    Γöé            Γöé
ΓöéCANNOT CREATE NEW   Γöé0x00000015  Γöé
ΓöéFILE                Γöé            Γöé
Γöé                    Γöé            Γöé
ΓöéNO SAMPLES          Γöé0x00000012  Γöé
Γöé                    Γöé            Γöé
ΓöéCANNOT PLAYBACK     Γöé0x00000013  Γöé
Γöé                    Γöé            Γöé
ΓöéCANNOT RECORD       Γöé0x00000014  Γöé
Γöé                    Γöé            Γöé
ΓöéNO MMPM INSTALLED   Γöé0x00000020  Γöé
Γöé                    Γöé            Γöé
ΓöéMMPM NOT ENABLED    Γöé0x00000021  Γöé
Γöé                    Γöé            Γöé
ΓöéFREE MEMORY NOT     Γöé0x00000022  Γöé
ΓöéENABLED             Γöé            Γöé
Γöé                    Γöé            Γöé
ΓöéGENERAL FUNCTION    Γöé0x00000030  Γöé
ΓöéERROR               Γöé            Γöé
Γöé                    Γöé            Γöé
ΓöéGENERAL COMMAND     Γöé0x00000031  Γöé
ΓöéERROR               Γöé            Γöé
Γöé                    Γöé            Γöé
ΓöéPROGRAM NOT         Γöé0x000000ff  Γöé
ΓöéREGISTERED          Γöé            Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 3. PlSndX ΓòÉΓòÉΓòÉ

                                   PMsndX 2.11
                                       by
                                William S. Hiles
                             copyright WiSHware Inc.

PlSndX is part of the family of programs grouped under the name PMsndX  Plsndx
has been designed to utilize the capability developed in EdSndX for loading and
saving many formats. This tool has been optimized to provide options which let
the program minimize memory requirements for playback and has the same
drag/drop features of the EdSndX program.

Many of the features of PlSndX will seem familiar to anyone using EdSndX
because they share the same libraries for most of the code.  The advantage to
this is that any fixes made to either program are automatically reflected in
the other program.

PlSndX is not intended to provide any editing capabilities but does have the
capability to save a file once loaded. This feature has been retained to allow
a file to be saved in any of the supported formats after the file has been
loaded from another application.  Such an example is the IBM WebExplorer where
a sound file may be brought down over the net and played with PlSndX.  If the
Free memory after loading feature has not been enabled, PlSndX can be used to
save the sample to disk in any format that the operator chooses.

A number of features of PlSndX sets it apart from other sound players.  These
include the ability to automatically detects if another copy of the player is
running and saves resources by communicating with the running copy of PlSndX to
load the files, double buffering for quick playback, and automatic rate
adjustment to ensure proper playback.


ΓòÉΓòÉΓòÉ 3.1. Control Panel ΓòÉΓòÉΓòÉ

PlSndX utilizes the same concept as EdSndX in that it has a control panel that
serves as the point of control for the program.  From this control panel, the
operator may control playback of a sample, volume for the audio system, or
lauch windows to utilize features of the program.  The control panel for PlSndX
is shown below.

The controls of interest for PlsndX are:

 System Menu     The system menu for the control panel
 Stop button     Stop audio playback
 Play button     Start audio playback
 Rewind button   Rewind the current play position
 Volume control  Adjust the playback volume


ΓòÉΓòÉΓòÉ 3.2. System Menu ΓòÉΓòÉΓòÉ

Like any other OS/2 program, PlSndX provides a system menu which is used to
access the standard controls for manipulating the application on the desktop.
The following figure illustrates the system menu for PlSndX.

Notice that the Open... and Save as... items are placed in the system menu
because PlSndX does not have a menu bar for these items.

The menu items provided in the system menu are:

 Restore        Restore the windows after being minimized
 Move           Move the control window
 Size           Resize the main control panel
 Minimize       Minimize all of the windows of EdSndX to an icon
 Close          Close the all windows and exit
 Help           Bring up the help system
 Properties     Change program operational parameters
 Open...        Read a file from disk
 Save as...     Save a file to disk*

 Note:  * The Save as... menu item is disabled whenever a sample has not been
        loaded or when it has been discarded because the Free memory after
        loading option has been selected


ΓòÉΓòÉΓòÉ 3.2.1. Resizing the control panel ΓòÉΓòÉΓòÉ

PlSndX provides a border for resizing the control panel. However, unlike
EdSndX, the buttons for the control panel will not resize to fit the window.
The buttons are bitmaps which are animated during playback.  As a result, large
bitmaps would take more time and processor resources to animate so the size of
the buttons has been fixed to be mathematically proportional to the default
font size for the window.  The buttons are twice the maximum height of the
font.  The volume button is set to be the maximum height of the font plus about
5 pixels in either direction.


ΓòÉΓòÉΓòÉ 3.2.2. Drag and Drop ΓòÉΓòÉΓòÉ

The control panel is also the place to receive drag/drop operations.  Such
operations are accomplished by dragging a sound file to the control panel and
dropping it on anywhere within the border of the panel and below the titlebar.
PlSndX will automatically load the sample into memory and load the MMPM buffers
in preparation for playback. See drag/drop for more information on  performing
drag/drop operations.


ΓòÉΓòÉΓòÉ 3.2.3. Buttons ΓòÉΓòÉΓòÉ

PlSndX provides the minimum size application to provide the controls necessary
to provide playback of a sample.  It does not provide a record button.  The
buttons are generally animated such that during playback, the face of the
buttons moves to indicate the action being performed.


ΓòÉΓòÉΓòÉ 3.2.3.1. Stop ΓòÉΓòÉΓòÉ

The Stop button is the one to the farthest left on the control panel and is
used to stop playback.  If playback has already been stopped, this button is
disabled as indicated by a greyed out look to the button.

PlSndx does not automatically rewind a sample when the stop button is pressed.


ΓòÉΓòÉΓòÉ 3.2.3.2. Play ΓòÉΓòÉΓòÉ

The play button is the primary point of action for PlSndX. The play button is
an animated button which displays a moving arrow during playback.  It also
overlays the current time index on the playback button to provide a reference
for how much time has elapsed in the sample. A sample can be played in a number
of different ways.

A sample may be played by loading it into memory through either the open dialog
from the system menu or through drag/drop operations and then pressing the play
button after the buffers have been loaded.

If the Play on Commandline load property has been selected, the sample can be
played immediately after the buffers have been set up when the sample is loaded
from the command line.  This is one of the primary uses of PlSndX in that it
can load a sample from the command line and play it immediately.  This can also
be combined with the Exit after commandline play property to automatically
terminate PlSndX after it has played all samples on the command line.  This is
particularly useful when the program is used to play samples that are
downloaded through an internet connection through a WEB explorer.

When multiple file selections are made or when multiple files are queued up for
playback through either the commandline or pipes, the file must play in its
entirity before the next file is loaded.  If playback is stopped, playback will
continue from the point where it left off and the sample will be played in its
entirity before moving on to the next file.  When the repeat option is enabled,
PlSndX will not move on to the next sample until the repeat feature is
disabled.


ΓòÉΓòÉΓòÉ 3.2.3.3. Rewind ΓòÉΓòÉΓòÉ

PlSndX does not automatically rewind a sample after playback has been stopped.
When playback is stopped, the rewind button will be enabled so that the
position of playback may be started at the beginning.


ΓòÉΓòÉΓòÉ 3.2.3.4. Volume ΓòÉΓòÉΓòÉ

The volume control for PlSndX is identical to that of EdSndX.  The volume
control is a sliding bar which sets the volume to a percentage of the maximum
volume for the audio device.  The operation of the volume control is similar to
a standard slider except that it does not have an associated button.  Rather,
it is like an analog volume control such that the slider moves to the right and
left using the mouse and the width of the slider indicates the volume.
Additionally, the actual percentage of the volume is indicated in the display
for convenience.

The slider may be moved using the mouse button or the normal keys associated
with scroll bars.  By selecting the area near the edge of the sliding portion
of the control, the slider can be captured and the mouse can be used to drag
the volume to the desired position.  If playback is occurring, the effect is
immediately heard.  The area to the left or right of the slider edge may also
be selected with the first mouse button to move the slider one percent up or
down depending on the position that is selected.  Holding the mouse down causes
the slider to increase at a rate of about 1 percent per tenth of a second.
Finally, the second mouse button may be used to move the slider to a specific
position quickly.


ΓòÉΓòÉΓòÉ 4. Drag and Drop ΓòÉΓòÉΓòÉ

All PMsndX programs supports Drag and Drop of all sound files other than the
RAW formats and performs a COPY operation when a file is dropped onto any of
the PMsndX programs. To use this capability, the sound samples must be stored
in a file.  If an application attempts to transfer data without specifying a
filename, PMsndX will request that the application RENDER the file before
transferring it to PMsndX.  The request for rendering the file before transfer
is transparent to the user, but not all applications are capable of rendering
and may not be able to transfer the file to EdSndX.

To drag a sample to PMsndX, use the second mouse button (usually the right
mouse button) to select the file.  While holding the second mouse button down,
move the mouse pointer over the PMsndX control panel and lift the mouse button.
PMsndX will then attempt to load the file using the same rules as the Open
dialog function uses.


ΓòÉΓòÉΓòÉ 5. Properties ΓòÉΓòÉΓòÉ

PMsndX can store a number of properties (user options) that users commonly set
in a file called pmsndx.ini.  The location of this file may be specified only
if PMsndX is registered; otherwise, the file will be located wherever the
executable program is started. From the PROPERTIES dialog box the user may
select to save the current window positions, open and save file path, maximum
memory, MMPM/2 options, and REXX options.

After the user has set all of the information in the PROPERTIES dialog box, the
ACCEPT button must be used to save the changes. When this button is pressed,
the changes are applied.

Note:  Changes to the maximum memory will be checked when a new sample is
       loaded or when an opertion that requires memory is attempted.

 To restore the PROPERTIES box to the settings the last time the APPLY button
 was pressed, the CANCEL button can be used.  All information entered by the
 user is cleared and the PROPERTIES remain unchanged.

 The window positions and file paths are maintained as long as PMsndX is
 running.  When PMsndX is terminated, it will not save the current positions
 and paths for file operations unless the boxes are checked in the PROPERTIES
 dialog box.  Selecting these buttons has no effect on remembering the current
 window positions during a single session; rather, they only affect saving the
 information between sessions.

 Note:  The information in the PROPERTIES dialog box is only saved when the
        program is terminated.

 Finally, to remove the Properties dialog box from the screen, select close
 from the system menu of the properties dialog or double click on the system
 menu icon for the properties dialog.  If the APPLY button has not been
 pressed, any changes made to the display will be lost.


ΓòÉΓòÉΓòÉ 5.1. Audio Properties ΓòÉΓòÉΓòÉ

Enable MMPM/2 Support

PMsndX supports playing samples from memory directly to the MMPM/2 digital
audio device of OS/2.  This allows samples to be played without having to save
the sample to disk in the native .WAV format.  The PROPERTIES dialog box
provides controls for disabling or enabling MMPM/2 support and for controlling
the actions taken when a file is loaded Additionally, the digital audio device
may be specified.

If the MMPM/2 capabilities of the program are not needed or if MMPM/2 support
is not installed on a particular system, the MMPM/2 may be disabled from the
PROPERTIES dialog box.  By disabling the MMPM/2 support, the button on the main
control panel for AUDIO is disabled.  By default the program will enable MMPM/2
support.  If MMPM/2 is available but disabled and the AUDIO button is selected,
a message is displayed to the user to indicate that the setting should be
turned on from the PROPERTIES dialog box.

The controls for MMPM/2 and the ability to play the "playlist" using MMPM/2
utilize the files SW.DLL and MDM.DLL.  These are part of the standard MMPM/2
distribution and must be present in the DLL path for the MMPM/2 portion of this
program to operate.  The MMPM/2 support is not linked into the executable of
this program.  Rather, it is only loaded when the user enables it.  This allows
the program to run on machines which do not have MMPM/2 installed.

The MMPM/2 functionality of PMsndX has been implemented to share the audio
device with other programs on the system. However, by disabling the MMPM/2
support, the audio device is freed up completely.

Share audio device

The audio device can be shared with the system such that while a sound is
playing, it may be interrupted by system sounds. Sharing the audio device
allows sounds to interrupt playback but may be desirable at all times.  When
the audio sharing is disabled, system sounds will come out of the standard
speaker in the form of a beep.

Play 16 bits on 8 bit audio

The Play 16 bits on 8 bit audio option allows 16 bit samples to be played on 8
bit audio adaptor.  By default, whenever any PMsndX program is started, it will
interrogate the audio device to determine the capabilities and automatically
play 16 bit samples on 8 bit adapters if the adapter does not support 16 bit
playback.  This feature can be overridden by setting or clearing the checkbox;
however, the changes made to this box are not saved between sessions and will
automatically be set whenever the program is started.  This box can be set and
cleared to allow the user to determine the overall effect of the setting on
audio playback.  Although most samples will produce square waves (resulting in
noisy results), some will play (most notably .au files).  Although the data is
sent to the audio device in 8 bit format, it is still maintained in its
original format and all manipulations including saving the file are performed
in the original size of the file.

Note:  When this option is selected, all files are played as 8 bit samples
       regardless of what is supported by the audio adapter.  Use this option
       only if you have an 8 bit card!

 EOF detection zone

 When playing a file, PMsndX must detect when the cuepoint reported by MMPM/2
 is near the end of the file so that it can rewind it.  Unfortunately, the
 cuepoint must be converted to an index value and then compaired to the length
 of a sample and the roundoff of that conversion creates a window or zone which
 the cuepoint cannot exist.  To compensate for this, an End Of File detection
 zone is provided which is used to determine if the playback needs to be
 rewound.  This zone must be set sufficiently small so that playback is not
 rewound whenever playback is stopped. A default value of 300 has proven to be
 a good zone but the value can be adjusted by the user if necessary. The range
 of values for this settings is between 0 and 32767.

 Note:  Playback does not stop till either the stop button or the MMPM/2 system
        reports an end of file condition regardless of this setting.  This
        setting only affects the behaviour of playback when playback is
        restarted once the end of file has been reached.

 Device

 Obviously not every machine has the same digital audio device.  PMsndX
 provides a means to use a different audio device than the default digital
 audio interface.  By default the device name is Waveaudio01.  Any Waveaudio
 device may be selected by entering the device name in the Device entry field.

 Note:  Setting the audio device to an invalid string will cause random errors.
        The worst case is the PMsndX will crash whenever the AUDIO dialog is
        opened.  To reset the audio device back to Waveaudio01, clear this
        field and then exit PMsndX.  When PMsndX is reloaded, it will reset the
        device to Waveaudio01.


ΓòÉΓòÉΓòÉ 5.2. Memory Properties ΓòÉΓòÉΓòÉ

Auto

PMsndX takes advantage of OS/2's advanced memory management facilities.  When
the program is started, it only takes up the memory required for the executable
to load.  PMsndX then only requests memory from OS/2 when an operation requires
storage space for a sample.  The maximum memory limitation is provided to avoid
overcommitting the memory in the system and creating a large swap file.

Memory is primarily used to hold samples for operations; however, whenever the
sound is manipulated in such a way that either the output has a different
number of samples or the operation requires the samples to remain in tact
during the entire operation, additional memory is used to hold the new data.
Once the operation has been completed, the memory is freed unless the UNDO
feature is enabled. When setting the maximum memory, the user must take into
account the size of the data in memory as well as the size of the results of
any operations. With the exception of Sampling Rate changes, the maximum memory
requirements will not exceed twice the size of a sample.  When changing rate,
the size is dependent on the new sampling rate.  If the new rate is higher than
the current rate, the memory requirements will increase.  If the new rate is
lower than the original rate, the memory requirements will shrink.

If the user selects the AUTO mode for memory (the default), PMsndX will request
as much memory as OS/2 will give it.

If the user chooses to limit the memory to a specific value, the AUTO checkbox
can be turned off and a value may be entered.  Since the minimum OS/2 memory
block size is 4096 (4k) bytes, the user may specify the number of 4k pages for
the limit.  The user may either use the up and down arrows to increment or
decrement the amount of memory or may place the cursor in the window and type
the specific value.


ΓòÉΓòÉΓòÉ 5.3. Misc Properties ΓòÉΓòÉΓòÉ

Ignore unknown header blocks

Many sound formats contain optional header blocks and user defined header
blocks which PMsndX may not support.  By default, PMsndX will warn the user
when it encounters an unsupported header block.  By selecting this option,
PMsndX will not display the warning.

Note:  When the unsupported header block warning is displayed, PMsndX provides
       the option of disabling the warning by selecting YES.  This is not the
       same as the Ignore unknown header blocks option and only disables the
       warning for the current session of PMsndX.

 Require header in .au files

 Samples taken from a Sun usually contain a header but there are files which do
 not.  Typically a Sun file will not contain a header if the sample is recorded
 from the audio device as if it were a file (e.g. "cat < /dev/audio >
 sample.au").  By default, PMsndX will recognize the extension of .au and force
 a headerless file to be loaded as a sun file with a sampling rate of 8012 Hz.
 When this option is selected, headerless Sun files must be loaded using the
 format RAW .ul format.  This method for loading headerless Sun files allows
 the user to specify the sampling rate for the file.

 Force all .AU to ULaw

 PMsndX is capable of loading and saving .AU files formatted with ULAW, LINEAR
 8 (signed 8 bit), and LINEAR 16 (signed 16 bit) samples.  Since the ULAW
 format is a lossy compression technique, it is best to save data in its native
 8 or 16 bit format.  Some machines cannot play .AU files unless they are
 stored in ULaw format and PMsndX has settings which allow the user to control
 the action taken when a file is saved which is not ULaw.

 The Force all .AU to ULaw setting is a tri-state checkbox. When the box is
 cleared, PMsndX will save the data in the best format to match the current
 format.  When the button is in the checked state (indiated by a checkmark in
 the box), PMsndX will always save the data in ULaw format regardless of the
 current format.  When the box is set in the intermediate state (a greyed out
 box), PMsndX will present the user with the following message:

 The current data format is not ULAW.  The .AU file format supports this dtaa
 type; however, some systems only support the ULAW format.

 At that time, the user may select to either force the file to become ULaw or
 to allow PMsndX to save in the most accurate format for that data.

 If you find that a .AU sample cannot be played on another platform and results
 in noise or an error, try saving the data in the ULaw format to correct the
 problem.

 Location of .INI

 By default, the file pmsndx.ini is stored at the location of the executable
 program.  However, this location may be changed by modifying this field.  The
 path is tested for validity when the parameters are applied; and, if the path
 is found to be invalid, and error is displayed and the current path is left
 unchanged. If the path is blank, the default path will be restored.

 Note:  This option is only valid when the program is registered.  The data for
        the path to the pmsndx.ini file is stored in the os2.ini file which is
        only modified if the program is registered to prevent storing data in
        the os2.ini when a user is just testing out the program.


ΓòÉΓòÉΓòÉ 5.4. REXX Properties ΓòÉΓòÉΓòÉ

STDIN color

This defines the color of text read from STDIN in the REXX output window.  By
default, this is set to BLACK.

STDOUT color

This defines the color of text written to STDOUT in the REXX output window.  By
default, this is set to BLACK.

STDERR color

This defines the color of text written to STDERR in the REXX output window.  By
default, this is set to RED.

COMMAND color

This defines the color of the PMsndX commands written in the REXX output
window.  By default, this is set to GREEN.

REXX display history

Setting the number in the entry field for this item modifies the number of
lines maintained by the REXX output window and may take on values between 64
and 0x7fff.  The default is 64 Changes made to this value will be used on
successive REXX command scripts.  Each line of REXX output reserves 256
characters of data and as a result, the number of rexx lines maintained for
history impacts the memory requirements of the program while REXX is running.

Note:  Changes to the REXX display history parameter does not take effect till
       the next command script.  (i.e. If a REXX output window is open when
       this parameter is changed, the number of lines currently held is not
       changed.)


ΓòÉΓòÉΓòÉ 5.5. Startup Properties ΓòÉΓòÉΓòÉ

Show Footnote window

PMsndX can display a window at the bottom of the main control panel with text
indicating the action of each of the items under the mouse pointer.  When this
box is set, the window is displayed.

Note:  The effect of setting this item will not be seen until EdSndX is
       restarted.

 Save Window positions

 During a session, the user can move any of the dialog boxes around on the
 screen.  If the WINDOW POSITIONS box is checked, these window positions will
 be saved when the program is terminated.  If this button is deselected before
 the program is terminated, the next session will revert to the previous window
 positions saved by the program.  By default, if no window position has been
 saved for a particular window, the window will be opened in the lower left
 corner of the desktop.

 Save file Open paths

 The cache of files that have been successfully opened may be saved between
 sessions by selecting the Save file Open path checkbox.  If this button is
 deselected before the program is terminated, the next session will revert to
 the paths from the previous session. If no information is saved for the
 program at any time, the current path will become the default path for open
 operations.

 Save file Save paths

 The cache of files that have been successfully saved may be saved between
 sessions by selecting the Save file Save path checkbox.  If this button is
 deselected before the program is terminated, the next session will revert to
 the path from the previous session. If no information has not been saved
 between sessions, the current path will become the default path for save
 operations.


ΓòÉΓòÉΓòÉ 5.6. PlSndX Specific Properties ΓòÉΓòÉΓòÉ

The information for this page applies only to PlSndX but can be set from any
PMsndX application.

Automatic rate adjust

When this feature is enabled, PlSndX will automatically adjust the rate of the
sample to the nearest multiple of 11025 Hz.  This feature is provided so that
samples which have odd rates can still be played.

Note:  Rate adjustment is only necessary when the sampling rate of the loaded
       sample is not a multiple of 11025 Hz.  When rate adjustment is necessary
       and this feature is enabled, the play button will display "Adj Rate"
       while the rate effect is being applied.

 Play on commandline load

 When the Play on commandline load box is selected, a sample will be played
 when specified on the command line.  The AUDIO dialog is opened after the file
 has been loaded to allow for user control.  This feature can be used in
 conjunction with the Exit after commandline play to allow a sample to be
 played from the command line such that control is returned to the calling
 program after playback has completed.

 If this parameter is not specified, the sample will still be loaded from the
 command line; however, it will not be played until the play button is pressed.

 Exit after commandline play

 The Exit after commandline play option provides the ability for PlSndX to exit
 after playing the sample when the file is loaded from the command line.  This
 is primarily intended to provide a means to play any of the supported formats
 from the command line.

 Free memory after loading

 When this feature is enabled, the original generic format sample data is
 automatically deleted after the sample has been converted to the proper
 buffers for the MMPM/2 audio system. This has the advantage that the overall
 memory requirements for a particular sample to play is reduced; however, it
 has the negative effect that the sample cannot be saved after the playback is
 completed.  This option has been provided for the case where the operator has
 no intention of saving the file when it has been loaded from the command line.

 Enable Quick queueing

 PlSndX has the ability to double buffer sound samples so that they can be
 played back in quick succession.  This feature is only enabled when the Free
 memory after loading is checked.  This form of operation is disabled by
 default because it defeats the advantage of the Free memory after loading when
 it creates the file buffer.  The operation is very simple.  Since the main
 buffer is freed after the MMPM/2 buffers are filled, it is available to load
 the next sample.  When this feature is enabled, the buffer is automatically
 loaded while the playback of the current file continues.  As soon as the
 current file completes, the new buffer is passed to MMPM/2 and the cycle
 repeats till there are no more files in the queue.  The files may be queued in
 any of the methods for loading a file such as selecting multiple files from
 the OPEN dialog, selecting a file in the OPEN dialog while playback is
 ongoing, or by utilizing the piping feature of the commandline playback.


ΓòÉΓòÉΓòÉ 5.7. EdSndX Specific Properties ΓòÉΓòÉΓòÉ

Enable UNDO

When a sample file is changed through the editor, a tools or a new file is
loaded, the sample is buffered so that the operation can be undone.  To access
the UNDO feature, selecting the UNDO button on the Edit dialog.  The UNDO
feature is only available when PMsndX is registered.

Note:  By default the UNDO feature is not enabled to conserve memory.

 Use Displayed Channel

 Some of the tools of the toolbox can operate on a selected channel or all
 channels of a sample.  These tools provide a checkbox within the tool dialog
 to select the mode of operation and the default mode can be set through this
 property.

 Use Selected Range

 Some of the tools of the toolbox can operate on a selected range or on the
 entire sample.  These tools provide a checkbox within the tool dialog to
 select the mode of operation and the default mode can be set through this
 property.


ΓòÉΓòÉΓòÉ 5.8. EdSndX Editor Specific Properties ΓòÉΓòÉΓòÉ

 The settings on this page are identical to those found in the menus of the
editor and are provided here to maintain a consistent place for controlling all
settings.

Info

This setting is used to control the display of the information section of the
editor window.  This setting is the same as the Display Info in the editor
menu.

All Channels

This property is used to control the display of the channels in the editor
window.  This setting is the same as the All Channels in the editor menu.

Delay AUDIO Loading

This property is used to control the loading of the audio buffers within the
editor.  This setting is the same as the Delay AUDIO Loading in the editor
menu.

Setup AUDIO at Play

This setting is used to control the loading of the audio buffers when the play
button is pressed in the editor window.  This setting is the same as the Load
AUDIO at playback in the editor menu.

Auto Repeat

This property allows the user to control the repeat feature of the audio
portion of the editor window.  This setting is the same as the Auto repeat in
the editor menu.

Format MM:SS.hhhh

This property is used to control the display of the index for sample
positioning in the editor.  This setting is the same as the Format in the
editor menu.

Play mode Range

This property is used to select the method for playback.  This setting is the
same as the Play mode in the editor menu.


ΓòÉΓòÉΓòÉ 6. Technical Issues ΓòÉΓòÉΓòÉ

Memory Usage: I have worked with means for storing and converting from one
format to another efficiently.  Initially I tried to store things in a data
structure which was a union of all of the types of data that are used by the
computers.  However, converting from one format to another was difficult and
each effect had to be able to understand the initial and final format.  This
became a headache considering that there can be either signed or unsigned
samples of sizes byte or word.  As new effects were added, it became
unmanageable.  At a sacrifice to memory efficiency, I have changed it to store
all data as a signed SHORT (2 byte) sample.  The effects then operate
generically on the samples and the only time that the type of data is important
is when reading or writing the samples.  The savings in complexity justified
the memory requirements.  As a result, if a sample is 1k of bytes (.wav
format), then in memory it will take up 2k.  Currently the program will only
read and write 8 and 16 bit samples. Since I don't know of any sound cards that
can sample at greater bit sizes, this is the limit.  In the future, this
approach to memory usage can be easily extended to 32 bits without rewriting
every part of the program.  In fact, to change the storage sizes, two
definitions have to be changed and then the proper input/output routines
written.  Simple? I think so.

Significant Changes in version 2.00:

Version 2.0 of PMsndX represents a significant change in the form and function
of the program.  All of the changes have been incorporated into the REXX
processing and in some cases, the results of the REXX operations may have
changed such that previously correct REXX scripts no longer work. This section
identifies the changes that are significantly different in the REXX scripts.

COMMANDS and FUNCTIONS:  All portions of the rexx scripts have been converted
to functions.  This eliminates a lot of confusion that was created in the
previous version.

FILE:  The FILE function has been changed to facilitate the multiple document
interface.  As a result, the FILE function no longer returns the full path;
rather, it returns a handle that is used to reference the file.  All functions
have been changed to expect and require the handle.


ΓòÉΓòÉΓòÉ 6.1. Additional known faults ΓòÉΓòÉΓòÉ

There is a known problem with PMsndX and version 3.0 of MMPM/2 which affects
the performance of the Audio playback. When running PMsndX under Warp, anything
which interrupts the playback of a sample (such as a system sound) will cause
PMsndX to hang the next time playback is requested. I have tried to correct
this but have found no solution at this time.  For this reason, I have provided
the option to have PMsndX open the Audio device without sharing it (the
default). This problem does not appear to affect PMsndX on previous versions of
OS/2 (i.e. 2.0, 2.1 and 2.11).

From an OS/2 window run the command SYSLEVEL.  If you receive the following
output, then your system will probably exhibit the problem.

      E:\MMOS2\INSTALL\SYSLEVEL.MPM
                   IBM Multimedia Presentation Manager/2
      Version 3.00   Component ID 562137400
      Type W
      Current CSD level: XR03000
      Prior  CSD level: XR03000

 To test to see if your system will encounter this problem, open a sample file
 and select the AUDIO button on the main control panel. Start playback by
 pressing the PLAY button and then pressing the PAUSE button.  Press the PAUSE
 button again to resume playback. If the PLAY button stops moving after the
 sample has finished playing, PMsndX will not lock up on your system.  You
 should set PMsndX to share the audio device by going to the startup properties
 page (from the main control panel system menu). If the playback button does
 not stop moving after the sample has finished, then you should avoid using the
 PAUSE button and leave PMsndX set so that it does not share the AUDIO device.

 I apologize for this problem, and a new revision of MMPM/2 will correct this
 in the future.

 Minor limitations:

   1. When recording a sample, the CD input cannot be used at this time.
   2. There is no way to edit multiple sounds at the same time.


ΓòÉΓòÉΓòÉ 7. Registration ΓòÉΓòÉΓòÉ

Registrations are available by contacting the Author. Paid registrations do not
expire.  The expiration feature is provided to allow trial periods for
businesses and packages which intend to distribute PMsndX at a cost to the
user.

Licensing and registration fees apply to the user interface and style of the
program but do not apply to the algorithms used to create the effects.  These
algorithms are public domain and may be copied and distributed freely.

I have put a lot of effort into making this program robust and very pleasing.
It has taken me more than a year and a half and 46,000 lines of code to get
this program to where it is now, and I would hope that if you like the program
and use it, you will appreciate it enough to send me a little cash to help fund
future work.  I don't expect much.

Asking for money is a sticky thing.  The big problem is to give people a
program so that they can play with it to see what it can do and yet hold back
enough to get people to want to register the program.  I put a lot of thought
into this and have considered the many ways that authors achieve their goals.
My solution was to disable the ability to read or write any formats other than
the PC (.WAV) and Sun (.AU) types, disable the UNDO capibility, and limit the
editing capability.


ΓòÉΓòÉΓòÉ 8. Shareware ΓòÉΓòÉΓòÉ

I have three options which I can offer which seem to follow with common
SHAREWARE practice.  A registration form is provided in the file ORDER.TXT and
the following are the options for registration.

1.  $10.00 will get you a password that will enable all of the functions of the
current version.

2.  $20.00 will get you a password that will enable all of the functions for
all versions up to the next major release.  If you chose to register using
option 2 first and then want to upgrade, I will give you a $5 credit and you
can get option 2 for $15.00.

3.  $40.00 will get you a password that will enable all of the functions for
all future versions.  If you have chosen to register using option 2 first, I
will give you a $10 credit and you can get the lifetime registration for
$30.00.  If you have registered with option 1 first, then I will give you $5
credit and you can get the lifetime registration for $35.00.

Note:  Please note.  These prices cover just the registration.  Shipping
       charges for the disks through the Postal service are extra.  If you
       order the program through the mail, add $5.00 to cover the media and
       shipping costs.  If you are an individual and do not have access to the
       internet, I can send you a disk and registration for the fee of $5.00 to
       cover the media and shipping costs.  Also, I also retain the right to
       deny registrations at any time.  I will typically deny registration to
       anyone who has an address that implies that it will be used in a
       corporate or government environment.

 Now, what do you get when you register.  Well, you obviously get a password
 that will enable all functions of the program.  The functions that are
 disabled for unregistered users are:

 Formats   Only .WAV and .AU format can be loaded and saved
 Editor    The Cut and Paste operations of the editor only work for the full
           sample (i.e. will not work for ranges)
 Undo      The UNDO function is disabled
 REXX      The REXX functionality is disabled

 In addition to that, I can provide limited technical support for paying users
 through regular phone service, email, or the US Postal service.  A number of
 people have contacted me to ask for special programs (e.g. programs that will
 just play any format without the overhead of the editor or a program that will
 just convert between formats).  These will be fairly easy to create using the
 existing objects of PMsndX.  If you are registered for PMsndX, these programs
 will automatically recognize the registration and work on your system.

 If and when you register, you will receive a password through whatever means
 that you prefer.  If you choose the postal service, you will receive it via
 disk along with the latest copy of the program (remember to include an
 additional $5.00 to cover the shipping and media).  If you choose to receive
 your registration through email, you will receive an email message that can be
 imported using the FILE button of the registration dialog.  Registrations will
 be sent after your form of payment has cleared.

 Since PMsndX is provided as SHAREWARE, there is no provision for refunds.  In
 the event that you are dissatisified with the operation of PMsndX due to an
 error in loading or saving a format, contact me and I will fix the program if
 you can provide me with a copy of the file that is causing the problem or
 enough detail that I can recreate the problem.

 Send registrations to:

      Scott Hiles
      4421 Savannah St.
      King George, VA 22485

 WiSHware is a sole Proprietorship and can be reached through the phone at
 [phone].  This is the author's home phone and should not be called
 unless the author cannot be contacted through any other means.

 PMsndX is a form of SHAREWARE and as such requires a registration for all of
 the functions of the program to be used.  What makes PMsndX different from
 other shareware programs?  Well, simply put, any individual who contacts the
 author and sends a completed ORDER.TXT file will receive a free registration.
 You can email the completed ORDER.TXT file (after all, you don't need to send
 it through US Mail if it is free and you are not sending a check) to me at
 [e-mail].  The only time that a registration must be paid for is when
 it is used for business purposes in which an individual, company, or
 government agency uses PMsndX in the office environment or makes a profit from
 the use of PMsndX.  If you make a profit, then I want to make a profit.  This
 is not to say that I will not accept donations for my efforts; rather, they
 are not required for individuals.  This is the reason that the program still
 requires a password and is also the reason that the user must contact the
 author to get a registration.  It lets me keep track of who is using it, how
 popular it is, and how far the distribution has gotten.  Now, why is this
 tidbit hidden in the help file and not in plain sight?  It is the reward that
 you get for reading the help file.


ΓòÉΓòÉΓòÉ 9. Entering Registration Info ΓòÉΓòÉΓòÉ

Once you receive your registration you have a couple of options for entering it
into the program.  First, pull up either the Welcome or About dialog box from
the system menu of PMsndX.  Press the REGISTER button to bring up the
registration dialog box.

You may enter the data directly into the entry fields or you may have the
program scan a data file for your registration information. When entering data,
enter it exactly as it is shown in the file or text for your registration.  The
Name field must not have any additional spaces and it must be entered in exact
case. The password is 16 characters long and will never contain any space
characters.  It is case sensitive so be careful to get the case right.
Passwords never contain the upper case letter O or the upper case letter I to
avoid confusion with similar looking numbers.

When PMsndX scans a file for the password information, it looks for the
following keys:

      PMsndX Name:
      Through version:
      Expiration date:
      PMsndX Password:

 These lines can be anywhere in a file so there is no need to remove a mail
 header or extra information.  PMsndX will search the file for the specific
 text that it is looking for and extract it.

 The registration information is stored in the file called os2.ini.  This
 allows a copy of PMsndX to be run from a network and each machine can have
 it's own registration. This also allows the pmsndx.ini file to be copied form
 one machine to another without violating the licensing agreement.  Five items
 are stored in the os2.ini and total about 100 bytes.  Any .ini editor can be
 used to remove this information if the user wishes to delete PMsndX from the
 system.

 Note:  The information in the os2.ini file is only written when the program is
        registered.  This avoids adding stuff to the os2.ini file unless the
        user has chosen that the program is worth keeping.


ΓòÉΓòÉΓòÉ 10. Tradeoffs ΓòÉΓòÉΓòÉ

When PMsndX is operating on a sample for the clipboard, AUDIO, or the tools, it
stores the entire sample in memory.  This has the advantage that the program
can double buffer the sample for faster operation; but, it has the disadvantage
that it can take up a tremendous amount of memory to hold large samples.
PMsndX provides the user with a simple interface at the expense of resources on
the host computer.


ΓòÉΓòÉΓòÉ 11. Copyright ΓòÉΓòÉΓòÉ

The author makes NO WARRANTY or representation, either expressed or implied,
with respect to PMsndX, its quality, accuracy, merchantability, or fitness for
a particular purpose.  This software is provided "AS IS" and you, its user,
assume the entire risk as to its quality and accuracy.

This software is copyright (C) 1994, William S. Hiles.  All rights Reserved
except as specified below.

Permission is hereby granted to use, copy, and distribute this software (or
portions thereof) for any purpose, without fee, subject to these conditions:

(1) The eight files, edsndx.exe, plsndx.exe, pmsndx.hlp, readme.txt,
history.txt, license.txt, order.txt and file_id.diz must always be included
during distribution. Any alterations to the files must be clearly documented.
No changes may be made to the About screen or any of the copyright information.

(2) Permission for use of this software is granted only if the user accepts
full responsibility for any undesirable consequences.  The author accepts NO
LIABILITY for damages of any kind.

(3) Permission is not granted for the use of the author's name or company name
in advertising or publicity relating to this software or products derived from
it.

(4) Users are granted permission to collect fees for the distribution of
PMsndX, (such as BBS's that have a membership fee or a downloading charge, or
FTP sites that sell cdrom versions of their archives) but users are
specifically prohibited from selling PMsndX as a product or bundling PMsndX
with other products that are then sold.

(5) Unless otherwise negotiated in writing with the Author, registration
passwords for PMsndX may not be distributed in part or in whole.  Registrations
are provided to individuals (or for site licensing as negotiated at time of
registration) and may not be distributed or transferred.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The following formats are supported by PMsndX.

 APPLE (.aif)*  Apple 8/16 bit unsigned multi-channel samples
 SUN (.au)      Sun/DEC/NeXT 8 or 16 bit single channel signed data samples or
                8 bit ULaw samples.
 RIFF (.avi)*   OS/2 movie format (PMsndX extracts the Audio and discards the
                video information)
 MAC (.hcm)*    Apple Macintosh 8 bit single channel samples
 RAW (.ub)*     Raw 8 bit single channel unsigned samples without header
                information
 RAW (.sb)*     Raw 8 bit single channel signed samples without header
                information
 RAW (.uw)*     Raw 16 bit single channel unsigned samples without header
                information
 RAW (.sw)*     Raw 16 bit single channel signed samples without header
                information
 RAW (.ul)      Raw 16 bit U-Law single channel samples
 IRACAM (.sf)*  Software produced 16 bit signed samples
 PC (.voc)*     Creative Voice file format, 8 bit single channel unsigned
                samples
 SAMP (.smp)*   Turtle beach samplevision files
 PC (.wav)      Windows or OS/2 8 bit unsigned/16 bit signed multi-channel data
                samples
 REXX (.cmd)*   REXX command script
 *              Types identified by * are supported only when PMsndX is
                registered.

 The .WAV format is actually defined as a RIFF file.  The header and data are
 very robust and there are extensions for proprietary keywords and formats.
 PMsndX only supports the standard PCM format and will not load proprietary
 formats.  You will receive a STYLE error if it contains an unsupported format.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The bits in a word are stored such that the leftmost bit is stored first in the
first byte and the rightmost bit is stored last in the last byte.  If a word is
composed of 16 bits, the word would be written to a file starting with bit 16
and ending in bit 0.

The number 0x1234 (0001 0010 0011 0100) is actually stored as 0001 0010 0011
0100.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The bits in a word are stored such that the leftmost bit is stored first in the
last byte and the rightmost bit is stored last in the first byte.  If a word is
composed of 16 bits, the word would be written to a file starting with bit 7
and ending in bit 8.

The number 0x1234 (0001 0010 0011 0100) is actually stored as 0011 0100 0001
0010.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

There are four methods of transitioning channels in a sample. These methods are
used in various tools to provide a smooth transition from one end of a range to
another.  The four types of transitions are listed in the following text.

The first method is linear.  In this case, the increase or decrease in the
volume is constant over time.  This can be defined by the mathematical
equation:

volume(t) = volume(t) * t/interval

A second method for adjusting the volume is to use a geometric expression so
that the sample transitions slowly in the beginning of the range and then
changes quickly toward the end of the range. To transition a sample out slowly
over time a form of the function:

volume(t) = volume(t) * (1 - (t/interval))¤

The third method is exactly the reverse of the slow transition in which the
transition moves very quickly in the beginning of the range and then slowly
reaches the end of the range. The equation for this is as follows:

volume(t) = volume(t) * (t/interval)¤

Finally a fourth method is to have the samples make an immediate transition or
a step.  In this case, the transition is made immediately at the beginning of
the range.